Legal Information

Telephony Application Programming Interface (TAPI) Programmer's Reference

This is a preliminary document and may be changed substantially prior to final commercial release. This document is provided for informational purposes only and Microsoft makes no warranties, either express or implied, in this document. Information in this document is subject to change without notice. The entire risk of the use or the results of the use of this document remains with the user. The names of companies, products, people, characters, and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted. Complying with all applicable copyright laws is the responsibility of the user. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Microsoft Corporation.

Portions of this document specify and accompany software that is still in development. Some of the information in this documentation may be inaccurate or may not be an accurate representation of the functionality of final documentation or software. Microsoft assumes no responsibility for any damages that might occur directly or indirectly from these inaccuracies.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 1995-1998 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, MS, Windows, Windows NT, and Win32 are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries.

Other product and company names mentioned herein may be the trademarks of their respective owners.


Using the TAPI 2.1 Programmer's Reference

The Microsoft Win32 Telephony Application Programming Interface (TAPI) version 2.1 provides services that enable an application developer to add telephone communications to applications developed for operating systems that support the Microsoft® Win32® API, such as Microsoft® Windows NT® Workstation and Microsoft Windows® 95.

The TAPI 2.1 Programmer's Reference is intended to help experienced programmers learn the API for telephony for these operating systems, and to be used by developers familiar with the Win32 programming environment. Previous development experience with telecommunications or other telephony applications is helpful but not necessary.


Document Overview

This document presents general information about how to develop telephony applications and offers specific information about the functions, messages, and data types of the Telephony API. The sections include:

  • Telephony Overview describes the Win32 Telephony API and explains how to use it in Win32 applications.
  • The Telephony Programming Model explains the concepts programmers should know before they begin development of telephonic applications. It includes sections that describe the uses of telephony's device classes, addresses, and other topics.
  • TAPI Applications refers to the source code of a telephonic application (supplied with the Microsoft Platform SDK) to illustrate how to create a functional Win32 application.
  • Multiple-Application Programming details what developers need to know when programming more than one application to work together or among other applications.
  • Call States and Events describes the call states through which a call transitions as it is established or disconnected.
  • Supplementary Line Functions describes some of the more advanced functions used to create telephonic applications, including media monitoring, media control, and call conferencing.
  • Line Devices Overview explains the line device class and describes the operations that can be carried out on line devices.
  • Phone Devices Overview describes the phone device class and the functions TAPI provides to use phone devices.
  • Assisted Telephony Overview tells how to add basic telephonic functionality to applications that don't require the flexibility or control provided by the full Telephony API. Readers whose development goals do not include the creation of new applications with a variety of telephonic functions may need to read no further than this section.
  • TAPI Device Classes describes device classes, the related physical devices or device drivers through which applications send and receive the information or data that makes up a call.
  • TAPI Quick Function Reference lists the functions of TAPI, a brief description of each, and the nature of each result: synchronous or asynchronous.
  • TAPI Unicode Support identifies which TAPI functions have Unicode versions and identifies the parameters and structure members that contain Unicode strings. This section also lists functions that do not have Unicode versions.
  • TAPI Reference contains detailed information about the line device, phone device and assisted telephony functions, messages, structures and constants.
  • TAPI Client Management contains overview, setup, and reference information, including a set of new extensible client management functions for enhanced telephony client management and control by a telephony service.


TAPI Versions

There are a number of versions of the Telephony Application Programming Interface (TAPI): versions 1.3, 1.4, 2.0, and 2.1. While most of these versions involved changes to the TAPI and Telephony Service Provider Interface (TSPI) documentation sets, there are other implications for each version, namely, architectural differences, operating system variations, redistributables, and telephony service provider (TSP) development issues.


TAPI Version 1.2 and Earlier

All versions of TAPI earlier than 1.3 were beta versions and should not be used any longer.


TAPI Version 1.3

TAPI version 1.3 (sometimes referred to as TAPI 1.03) was the first released version of the TAPI specification. The TAPI 1.3 system binaries (TAPI.DLL and others) are only found in the TAPI 1.0 SDK, which can only be found on the Microsoft® Developer Network (MSDN) Level II subscription. The system binaries (found in the REDIST directory) are redistributable but are designed only to run on Microsoft Windows® 3.1 and Windows® for Workgroups 3.11. They are not supported (and won't work) on any version of Microsoft Windows 95 or Microsoft Windows NT.

The headers and libraries that are used to develop a TAPI 1.3 application are only available in the TAPI 1.0 SDK and only support Win16 development. In fact, the TAPI 1.3 libraries are the only Win16 libraries available and must be used for all Win16 applications, regardless of the target platform or target version.

The TAPI 1.3 system binaries only support Win16, TAPI 1.3 TSPs, and applications.


TAPI Version 1.4

TAPI version 1.4 added a number of APIs, messages, constants, and structure elements to the 1.3 specification. TAPI 1.4 is a piece of Windows 95 – it is always present and cannot be separated out for separate distribution. TAPI 1.4 only supports 16-bit TSPs. However, it does allow 32-bit applications to be developed without having to worry about Win16 limitations.

The Win32 TAPI and TSPI headers in the Platform SDK are used to develop both TAPI 1.4 and TAPI 2.0 applications. While there were not many changes to the structures between these two specifications, there were changes to the APIs (specifically, Unicode support) that make it very important to note that the headers compile differently, depending on the TAPI_CURRENT_VERSION constant. For an application to work correctly on Windows 95, it must define this variable. For example:

#define TAPI_CURRENT_VERSION 0x00010004
#include <tapi.h>

Note TAPI_CURRENT_VERSION should be defined for all TAPI applications. While it is not strictly necessary for TAPI 2.0 development, future changes could occur to require this.

TAPI 1.4 system binaries (as part of Windows 95) support both TAPI 1.3 and 1.4 applications and service providers. While applications can be either Win16 or Win32, TSPs can only be Win16 DLLs.


TAPI Version 1.5

TAPI version 1.5 was designed specifically for Windows® CE, Version 1.0. It is a subset rather than a superset of TAPI 1.4, is only available on Windows CE, and is documented in the Windows CE developer documentation.


TAPI Version 2.0

TAPI version 2.0 added a small number of enhancements to the basic TAPI 1.4 functionality. However, there were some major architectural changes that greatly improved its stability. Most of the changes were fundamental changes necessary to bring TAPI to Windows NT and take advantage of Windows NT features (full Win32 support, services, Unicode). However, these changes were internal to TAPI and had little effect on TAPI applications.

TAPI 1.3 and 1.4 applications (Win16 applications by way of a thunking layer) work well on Windows NT 4.0. However, the effect on service-provider developers was significant. Service providers for Windows NT must be fully 32-bit Unicode DLLs that can run in the context of TAPISRV, not in the context of the TAPI application (as did all earlier Win16 TSPs). TSPs designed for TAPI 1.4 do not work on Windows NT.

TAPI 2.0 also added the important features of call center support and Quality of Service support.

The TAPI 2.0 system binaries (as part of Windows NT 4.0) support TAPI versions 1.3 and 1.4 for both Win16 and Win32 applications. However, they only support version 2.0 for Win32 applications and only support TAPI 2.0 service providers.


TAPI Version 2.1

TAPI version 2.1 made no changes to the previous TAPI 2.0 specification except for one major addition: Client-server functionality. Now telephony hardware can be installed on a telephony server that can be accessed from any computer on a network. A new set of functions were added to allow administration DLLs to be written to control who has access to remote resources.

TAPI 2.1 system components are redistributable to both Windows NT 4.0 and Windows 95. Future versions of both operating systems will come with TAPI 2.1 (or a later version) already installed. For Windows 95, this has further implications—it allows Windows 95 to support 32-bit TSPs. TSPs can be developed to run on both Windows 95 and Windows NT 4.0.

The TAPI 2.1 system binaries, when installed on Windows NT, support exactly the same applications and TSPs as TAPI 2.0, with the addition of TAPI 2.1 support.

The TAPI 2.1 system binaries, when installed on Windows 95, support:

  • Win16 TAPI 1.3 and TAPI 1.4 applications
  • Win32 TAPI 1.3, TAPI 1.4 and TAPI 2.0 applications
  • Win16 TAPI 1.3 and TAPI 1.4 TSPs
  • Win32 TAPI 2.0 TSPs


Versions and Conversions

Every TAPI application and TSP is developed for a specific version of TAPI. However, TAPI allows for quite a bit of flexibility between TSPs and applications. TAPI applications and TSPs do not have to use the same version in order to communicate.

The lineNegotiateAPIVersion function allows an application and TSP to agree on a version to use. A single TSP could be capable of handling more than one version, and an application must "fall back" to using an older version if using an older TSP. In lineNegotiateAPIVersion, the dwApiVersion parameter defaults to a value according to version, as follows:

TAPI Version | dwApiVersion default value
1.3 | 0x00010003
1.4 | 0x00010004
2.0 | 0x00020000
2.1 | 0x00020001

However, TAPI makes this much easier as long as the TSP itself is using a newer version than the application. If the TSP is indeed newer, then TAPI is capable of translating "down" to the application's version. For example, TAPI 2.0 TSPs do not need to be specifically capable of dealing with TAPI version 1.4. If a TAPI 1.4 application is run, TAPI converts all TAPI 2.0 structures and messages into TAPI 1.4 equivalents, or as close as possible. If there is no close approximation in TAPI 1.4, then all TAPI 2.0-specific information will be lost.


What's New for TAPI Version 2.1

TAPI version 2.1 implements TAPI Client Management, which provides full client-server telephony and enhanced server administration tools.

TAPI 2.1 works with Microsoft Windows NT Server version 4.0 and supports applications on Windows NT Workstation version 4.0 and Windows 95 operating systems. TAPI 2.1 provides a most powerful and flexible platform for developing and using computer-telephony integration (CTI) applications and provides complete client support for Windows 95.


TAPI Functions, API DLL Hooks, and Structures New for Version 2.1

The following tables list the items that are new in TAPI 2.1.

Functions
TAPICLIENT_ClientInitialize
TAPICLIENT_ClientShutdown
TAPICLIENT_Free
TAPICLIENT_Load
API DLL Hooks
TAPICLIENT_LineAddToConference
TAPICLIENT_LineBlindTransfer
TAPICLIENT_LineDial
TAPICLIENT_LineForward
TAPICLIENT_LineGenerateDigits
TAPICLIENT_LineMakeCall
TAPICLIENT_LineOpen
TAPICLIENT_LineRedirect
TAPICLIENT_LineSetCallData
TAPICLIENT_LineSetCallParams
TAPICLIENT_LineSetCallPrivilege
TAPICLIENT_LineSetCallTreatment
TAPICLIENT_LineSetCurrentLocation
TAPICLIENT_LineSetDevConfig
TAPICLIENT_LineSetLineDevStatus
TAPICLIENT_LineSetMediaControl
TAPICLIENT_LineSetMediaMode
TAPICLIENT_LineSetTerminal
TAPICLIENT_PhoneOpen
Structures
TAPIPERMANENTID.


Features in TAPI Version 2.0 and Later

TAPI version 2.0 and later contain these features:

  • Native 32-bit support. All core TAPI components are Win32, with full support for non-Intel processors (running Windows NT and Windows 95), symmetrical multiprocessing, multithreaded applications, and preemptive multitasking.
    To provide the best performance and support on the Windows NT and the Windows 95 platforms, the Win32 Telephony API and its service providers and supporting components are fully implemented as 32-bit components in Win32.
  • 32-bit application portability. Existing Win32 full TAPI and assisted TAPI applications which currently run on Windows 95 also run on Windows NT on the Intel x86 family of microprocessors without modification or recompilation.
  • 16-bit application portability. Existing Win16 full TAPI and assisted TAPI applications which currently run on Windows 95 and Windows® 3.1 operating system (using the TAPI 1.3 API) run on Windows NT without modification or recompilation.
  • Unicode support. Win32 applications can choose to call the existing ANSI TAPI functions or to call Unicode versions of functions that pass or return strings (functions with a "W" suffix).
  • Service processes. TAPI 2.0 adds mechanisms for notifying applications of telephony events that do not require the application to have a window message queue, thereby enabling background service processes to easily use TAPI services.
  • NDISTAPI compatibility. The existing support in Windows NT 3.5 for ISDN WAN miniports under Remote Access Service is preserved. NDIS WAN miniport drivers are supported under a kernel mode service provider without modification.
  • Registry support. All telephony parameters are stored in the registry. Telephony service providers and all stored parameters can be updated across the LAN.
  • Call Center support. TAPI supports functionality required in a call center environment, including the modeling of predictive dialing ports and queues, ACD agent control, station set status control, and centralized event timing.
  • Quality of Service (QOS) support. Applications can request, negotiate, and renegotiate quality of service (performance) parameters with the network, and receive indication of QOS on inbound calls and when QOS is changed by the network. The QOS structures are binary-compatible with those used in the Windows Sockets 2.0 specification.
  • Enhanced device sharing. Applications can restrict handling of inbound calls on a device to a single address, to support features such as distinctive ringing when used to indicate the expected media mode of inbound calls. Applications making outbound calls can set the device configuration when making a call.
  • User mode components. The full TAPI system, including top-level service provider DLLs, runs in user mode.

The following are additional version 2.X enhancements to existing TAPI features (now applicable to Windows 95 platforms running TAPI 2.0 or later):

  • Applications now receive LINE_APPNEWCALL messages (instead of LINE_CALLSTATE) as the first messages notifying the application of a new call.
  • Applications now receive LINE_REMOVE and PHONE_REMOVE messages whenever a line or phone device has been removed from the system.
  • LINECONNECTEDMODE_ constants now indicate when a call has been placed in the onhold state by the remote party. Also, an additional LINECONNECTEDMODE_ constant indicates to applications when entry into the connected state was confirmed by the network, or if it is just being assumed because confirmation from the network is impossible.
  • Applications now receive notification that ringing has stopped on a line device by receiving a LINE_LINEDEVSTATE message with the dwParam1 parameter set to LINEDEVSTATE_RINGING and both dwParam2 and dwParam3 set to zero.
  • The LINEDEVCAPS, LINEADDRESSCAPS, and PHONECAPS structures now include a listing of device classes supported by the device, with each supported device class terminated by a zero byte and the final class terminated by two zero bytes. A typical list for a voice modem might be:
    "tapi/line\0comm\0comm/datamodem\0wave/in\0wave/out\0\0"

    Applications can scan this list to see if a particular device supports device classes required for the application to properly function.

  • The LINEFEATURE_, LINEADDRFEATURE_, and LINECALLFEATURE_ sets of constants have been extended to allow applications to detect when various "flavors" of a function are available for use. For example, applications will be able to detect not only that a call can be transferred, but whether it is permitted to resolve the transfer as a three-way conference.
  • Applications can carry out a "one-step transfer" by using LINECALLPARAMFLAGS_ONESTEPTRANSFER with the lineSetupTransfer function.
  • Applications can carry out a "no hold conference" by using the LINECALLPARAMFLAGS_NOHOLDCONFERENCE option with the lineSetupConference function, allowing another device, such as a supervisor or recording device, to be silently attached to the line.
  • Applications can carry out a "transfer through hold" (on the systems with this capability) by using the linePickup function with a NULL target address. Check for the LINEADDRFEATURE_PICKUPHELD bit in LINEADDRESSCAPS and LINEADDRESSSTATUS for this capability.
  • The PHONECAPS structure now includes an indication of which hookswitch states can be set for each hookswitch device, and which can be detected and reported. Previously, applications could detect only the existence of each device without being able to determine which characteristics could be only monitored and not set.
  • The PHONESTATUS structure now also includes a dwPhoneFeatures member that indicates which phone operations can be performed at the particular moment in time that phoneGetStatus is called.


TAPI Functions, Messages, Structures, and Constants for Version 2.0

TAPI version 2.0 includes a number of functions, messages, structures, and constants that were either new (not available in previous versions of TAPI) or that changed in TAPI version 2.0. Although TAPI has now updated to version 2.1, the itemization of 2.0 changes is retained for the benefit of anyone previously using TAPI 1.4 or earlier.

The following tables list the items that changed in TAPI 2.0.

Functions | New/Changed
lineAgentSpecific | New
lineGetAgentActivityList | New
lineGetAgentCaps | New
lineGetAgentGroupList | New
lineGetAgentStatus | New
lineGetIcon | Changed
lineGetMessage | New
lineInitialize | Obsolete
lineInitializeEx | New
lineOpen | Changed
lineProxyMessage | New
lineProxyResponse | New
lineSetAgentActivity | New
lineSetAgentGroup | New
lineSetAgentState | New
lineSetCallData | New
lineSetCallQualityOfService | New
lineSetCallTreatment | New
lineSetLineDevStatus | New
phoneGetIcon | Changed
phoneGetMessage | New
phoneInitialize | Obsolete
phoneInitializeEx | New

Messages | New/Changed
LINE_AGENTSPECIFIC | New
LINE_AGENTSTATUS | New
LINE_APPNEWCALL | New
LINE_GATHERDIGITS | Changed
LINE_GENERATE | Changed
LINE_MONITORDIGITS | Changed
LINE_MONITORMEDIA | Changed
LINE_MONITORTONE | Changed
LINE_PROXYREQUEST | New
LINE_REMOVE | New
PHONE_REMOVE | New

Structures | New/Changed
LINEADDRESSCAPS | Changed
LINEAGENTACTIVITYENTRY | New
LINEAGENTACTIVITYLIST | New
LINEAGENTCAPS | New
LINEAGENTGROUPENTRY | New
LINEAGENTGROUPLIST | New
LINEAGENTSTATUS | New
LINEAPPINFO | New
LINECALLINFO | Changed
LINECALLPARAMS | Changed
LINECALLSTATUS | Changed
LINECALLTREATMENTENTRY | New
LINEDEVCAPS | Changed
LINEDEVSTATUS | Changed
LINEINITIALIZEEXPARAMS | New
LINEMESSAGE | New
LINEPROXYREQUEST | New
PHONECAPS | Changed
PHONEINITIALIZEEXPARAMS | New
PHONEMESSAGE | New
PHONESTATUS | Changed

Constants | New/Changed
LINEADDRCAPFLAGS_ Constants | Changed
LINEADDRFEATURE_ Constants | Changed
LINEAGENTFEATURE_ Constants | New
LINEAGENTSTATE_ Constants | New
LINEAGENTSTATUS_ Constants | New
LINEBEARERMODE_ Constants | Changed
LINECALLFEATURE_ Constants | Changed
LINECALLFEATURE2_ Constants | New
LINECALLINFOSTATE_ Constants | Changed
LINECALLPARAMFLAGS_ Constants | Changed
LINECALLREASON_ Constants | Changed
LINECALLTREATMENT_ Constants | New
LINECONNECTEDMODE_ Constants | Changed
LINEDISCONNECTMODE_ Constants | Changed
LINEERR_ Constants | Changed
LINEFEATURE_ Constants | Changed
LINEINITIALIZEEXOPTION_ Constants | New
LINEOPENOPTION_ Constants | New
LINEPROXYREQUEST_ Constants | New
LINETRANSLATERESULT_ Constants | Changed
LINETSPIOPTION_ Constants | New
PHONEFEATURE_ Constants | New
PHONEINITIALIZEEXOPTION_ Constants | New


Document Conventions for TAPI 2.1 Programmer's Reference

The type conventions used in the TAPI 2.1 Programmer's Reference are as follows:

Bold text | Bold letters indicate terms, such as function and structure names, that you must use exactly as shown.
ALL CAPS | All capitals typically indicate terms, such as message and constant names, that must be used exactly as shown.
Italic text | In introductory and explanatory text, italicized words indicate that a key term or concept is being introduced. In function and message descriptions, italics indicates a placeholder for which you are expected to provide a value or the name of a variable.
Monospaced text | Monospaced type indicates code samples and data-structure definitions.


Related Documentation on Telephony Services

Other documentation that may help you understand the telephony services as they apply to Windows includes:

  • Microsoft Platform Software Development Kit.
  • The Microsoft Telephony Service Provider Interface (TSPI) documentation (now part of the TAPI information set), which provides information on creating service providers for the Microsoft Windows family of operating systems that support TAPI.


Overviews

This section contains overviews on telephony, the telephony programming model, TAPI applications, multiple-application programming, call states and events, and supplementary line functions.


Telephony Overview

Telephony is a technology that integrates computers with the telephone network. With telephony, people can use their computers to take advantage of a wide range of sophisticated communications features and services over a telephone line.

The Telephony Application Programming Interface (TAPI) lets programmers develop applications that provide personal telephony to users. TAPI supports both speech and data transmission, allows for a variety of terminal devices, and supports complex connection types and call-management techniques such as call conferencing, call waiting, and voice mail. TAPI allows all elements of telephone usage, from the simple dial-and-speak call to international e-mail, to be controlled within applications developed for the Microsoft® Win32® application programming interface.


Using Telephony in Applications

Telephony capabilities help people get the most from telecommunications systems, allowing them to more efficiently manage their voice calls and control their data-transfer operations. You can use TAPI to bring this efficiency to any application—database manager, spreadsheet, word-processing application, personal information manager—any application that can benefit by sending and receiving data through the telephone network.

TAPI gives you a consistent set of tools for incorporating these features into your applications:

  • Connect directly to the telephone network rather than rely on a separate communications application.
  • Dial phone numbers automatically.
  • Transmit documents as files, faxes, or electronic mail.
  • Access data from news retrieval and other information services.
  • Set up and manage conference calls.
  • Receive, store, and sort voice mail.
  • Use caller-ID to automate the handling of incoming calls.
  • Control the operations of a remote computer.
  • Compute collaboratively over telephone lines.

TAPI provides your application with access to the telephone network, you provide your users with access to these features. This means you choose and create a user interface that is consistent with the rest of your application. For example, if you use drag and drop functionality extensively, you could let the user send files or faxes through the telephone to a colleague by dragging the icon of the file to an icon representing the colleague's destination. Similarly, you could let the user initiate conference calls by dragging three or four names from an electronic directory into a "Conference box" and clicking a "Connect" command. You choose the interface and let TAPI make and manage the telephone connections.


Telephone Network Services

TAPI provides access to a variety of telephone network services. Although these services may use different technologies to establish calls and transmit voice and data, TAPI makes these service-specific details transparent to applications. This means you can create applications that can take advantage of any available service without including service-specific code in your application.

Historically, most telephone connections in the world have been of the type POTS, or Plain Old Telephone Service. Most POTS calls are transmitted digitally except while in the local loop, the part of the telephone network between the telephone and the telephone company's central switching office. Within this loop, human speech from a household telephone is usually transmitted in analog format, and the digital data from a computer must first be converted to analog by a modem. Digital networks are gradually replacing analog in the local loop.

Using TAPI for POTS is straightforward because POTS is comparatively simple. It normally uses only one type of information (such as data or voice) per call, supports one channel per line, and so on. The vast majority of uses for TAPI are still POTS, and most telephony programmers will use TAPI only for POTS applications.

But TAPI is not restricted to POTS. TAPI also lets you make connections over other types of networks. More advanced kinds of data transmission methods are being developed, refined, and installed. For example, one important digital service is Integrated Services Digital Network (ISDN), which is expected to grow significantly in availability. ISDN networks have these advantages over POTS:

  • All digital
  • Less prone to error
  • Faster data transmission, with speeds up to 128 kilobytes per second (Kbps) on basic service
  • From 3 to 32 channels for simultaneous transmission of voice and data
  • An international standard

Error rates on ISDN networks are lower than with analog transmission because data travels from one end of the ISDN network to the other in digital format. Speeds of up to 128 Kbps are possible on Basic Rate Interface (BRI-ISDN) standard lines and much higher on Primary Rate Interface (PRI-ISDN) standard lines. When ISDN connections become more widespread, users will be able to send data to the recipient simultaneously with a voice call to that or another person. Each ISDN line, depending on its transmission rate, provides at least three channels (two for voice or data and one strictly for data or signaling information) and as many as 32 channels, for simultaneous, independently operated transmission of voice and data. BRI-ISDN lines provide two 64-Kbps "B" channels (B channels carry voice or data) and one 16-Kbps "D" channel (D channels carry signaling information or packet data). The PRI-ISDN lines for the U.S., Canada, and Japan have twenty-three 64-Kbps B channels and one 64-Kbps D channel. The European PRI standard offers thirty B channels and two D channels.

TAPI can also be used with other digital networks such as T1/E1 and Switched 56 service. With Switched 56, some local and long-distance telephone companies provide signaling at 56 Kbps over dial-up telephone lines. Switched 56 is quickly becoming available throughout the U.S. and in many other countries. It requires special equipment, and though its connection capabilities are limited to calls to other specially equipped facilities, its high speed and pricing make it a reasonable choice for many data communications needs. Switched 56 is used for data calls only.

TAPI can also be used with other services such as CENTREX, which provides a set of centralized network services (such as conferencing) without the need to install special equipment. With CENTREX, you pay for the use of telephone-company equipment over regular telephone lines. In addition, TAPI can be used with digital Private Branch Exchanges (PBXs) and key systems. Because TAPI is independent of the underlying telephone network, programming a PBX application using TAPI is the same as programming a POTS application using TAPI. An application that was originally programmed for a POTS environment can be used within a PBX environment with no changes to the application's source code.


Telephony Components

Based on the Windows Open Services Architecture (WOSA) model, Windows Telephony consists of the TAPI and TAPI32 dynamic-link libraries (which forward application requests to the telephony service for processing), tapisrv.exe (which implements and manages the TAPI functions), and one or more telephony service providers (drivers). TAPI provides a device-independent interface for carrying out telephony tasks. Service providers are dynamic-link libraries that carry out low-level and possibly device-specific actions needed to complete telephony tasks through hardware devices such as fax boards, ISDN cards, telephones, and modems. Applications link to and call functions in the TAPI dynamic-link library only; they never call the service providers directly.

When an application calls a TAPI function, the TAPI dynamic-link library validates and marshals the parameters of the function and forwards it to tapisrv.exe. TAPISRV (the telephony service) processes the call and routes a request to the appropriate service provider. To receive requests from TAPISRV, the service provider must implement the Telephony Service Provider Interface (TSPI). A service provider can provide different levels of the service provider interface: basic, supplementary, or extended. For example, a simple service provider might provide basic telephony service, such as support for outgoing calls, through a Hayes-compatible modem. A custom service provider, written by a third-party vendor, might provide a full range of incoming and outgoing call support.

A user can install any number of service providers on a computer as long as the service providers do not attempt to access the same hardware device at the same time. The user associates the hardware and the service provider when installing. Some service providers may be capable of accessing multiple devices. In some cases, the user may need to install a device driver along with the service provider.

Applications use the TAPI functions to determine which services are available on the given computer. TAPI determines what service providers are available and provides information about their capabilities to the applications. In this way, any number of applications can request services from the same service provider; TAPI manages all access to the service provider.

As long as an application does not depend on optional features, the applications can, without modification, use any services to carry out telephony tasks, even services made available after the application is developed. This is because the application always accesses the many different services through TAPI which translates the requests the application makes into the actual protocols and interfaces required.

The Telephony SPI is beyond the scope of this reference. For more information about TSPI and service providers, see the Microsoft TSPI Programmer's Reference.


Media Stream

The media stream consists of the information exchanged over a call. TAPI by itself provides control only for line and phone devices and does not give access to the content of the media stream. To manage the media stream, an application uses Win32 APIs, such as the Communication, Wave Audio, or Media Control Interface (MCI). For example, an application that provides an interface for managing fax or data transmission uses the TAPI functions to control and monitor the line over which bits are sent, but uses the Communications APIs to transmit the actual data.

In the same manner, the media stream in a speech call (where speech refers exclusively to human speech) is produced and controlled not by TAPI, but by one human talking to another. However, the line on which that call is established and monitored, and the call itself, remain in control of the TAPI application. Voice is considered to be any signal that can travel over a 3.1 kHz-bandwidth channel.


Special Hardware

Some of the more advanced capabilities of TAPI require that an application be able, for example, to retrieve data from telephones. Most telephones cannot be connected directly to computers to control speech calls and thus are currently incapable of supporting telephony functions beyond the passive role they play in POTS. In the future, users will install and configure telephone sets like other peripheral devices. The sets will be accompanied by cards that will control the flow of information between the computer and the telephone. Client/server configurations will also be possible that allow users to take advantage of telephonic services by connecting over a LAN to a server that has such a board and associated software installed.


Physical Connections

Lines and phones can be connected in a variety of ways to the desktop computer and the telephone network. The following examples show a selection of configurations that could be supported by a service provider. Some of the telephone hardware required to implement some of these examples is not yet widely available.

A phone-centric connection consists of a single POTS line in which the computer is connected to the switch through the desktop phone set. Such phone sets typically connect to the computer through one of its serial ports. When an application requests an action, the corresponding service provider sends telephony commands, which are often based on the Hayes AT command set (ANSI/TIA/EIA-602), over the serial connection to the telephone. This configuration is limited because it generally provides only line control. The computer does not have access to the media stream.

A computer-centric connection uses a computer add-in card or external box that is connected to both the telephone network and the phone set. The service provider can easily integrate modem and fax functions, as well as the use of the telephone as an audio I/O device.

A BRI-ISDN connection is similar to the computer-centric connection but allows for using the two B-channels in a variety of line configurations. A service provider can treat this connection in a number of ways:

  • As a single line device with a pool of two channels, allowing both channels to be combined for establishing 128 Kbps calls.
  • As two separate line devices, each with exclusive use of a single B-channel.
  • As two separate line devices, each drawing up to two channels from a shared pool of two B-channels.
  • As three line devices: one for each of the two B-channels and one for the combination.

In the latter two models, channels may be assigned to different line devices at different times.

In client/server networks, a pool of telephone ports attached to a server may be shared among multiple client computers using a local area network. The ports may be configured to assign a maximum number of line devices (the quota) to each client workstation. It is not unusual for the sum of all quotas to exceed the total number of lines.

Also, the assignment of lines through ports is dynamic. For example, a client computer with a quota of 2 may use ports 1 and 2 at one time and ports 7 and 11 at a later time.

The service provider for the pool may model this arrangement by giving each client workstation access to two line devices. This implies that the device identifiers (which are fixed) for each client are 0 and 1. If the application later requests information for device 0 and again for device 1, it must assume that the device capabilities for each device are constant, because that is the Windows device model. For server-based devices that are pooled as described in the example above, this constancy holds only for line devices that have identical device capabilities.

A LAN-based server might have multiple telephone-line connections to the switch. TAPI operations invoked at any of the client computers are forwarded over the LAN to the server. The server uses third-party call control between the server and the switch to implement the client's call-control requests.

This model offers a lower cost per computer for call control if the LAN is already in use, and it also offers reduced cost for media stream access if shared devices such as voice digitizers, fax and/or data modems, and interactive voice response cards are installed in the server. The digitized media streams can be carried over the LAN, although real-time transfer of media may be problematic with some LAN technologies due to inconsistent throughput.

A LAN-based host can be connected to the switch using a switch-to-host link. TAPI operations invoked at any of the client computers are forwarded over the LAN to the host, which uses a third-party switch-to-host link protocol to implement the client's call-control requests.

It is also possible for a private branch exchange (PBX) to be directly connected to the LAN, and for the server functions to be integrated into the PBX. Within this model, different subconfigurations are possible:

  • To provide personal telephony to each desktop, the service provider could model the PBX line associated with the computer (on a desktop) as a single line device with one channel. Each client computer would have one line device available.
  • Each third-party station can be modeled as a separate line device to allow applications to control calls on other stations. (In a PBX, a station is anything to which a wire leads from the PBX). This enables the application to control calls on other stations. This solution requires that the application open each line it wants to manipulate or monitor, which may be satisfactory if only a small number of lines is of interest, but may generate excessive overhead if a large number of lines is involved.
  • Model the set of all third-party stations as a single line device with one address (one phone number) assigned to it per station. Only a single device is to be opened, providing monitoring and control of all addresses (all stations) on the line. To originate a call on any of these stations, the application must only specify the station's address to the function that makes the call. No extra line opening operations are required. However, this modeling implies that all stations have the same line-device capabilities, although their address capabilities could be different.

A potential advantage of this model is a lowered cost per computer if the LAN is already in use, but a limitation would be a possible lack of media-stream access by the computers.

The computer in use need not be a desktop computer. It can also be a laptop or other portable computer connected to the telephone network over a wireless connection.

In a shared telephony connection, the computer's connection may be shared by other telephony equipment. For an application to operate properly in this arrangement, neither the application nor the service provider can assume that there are no other active devices on the line.


The Telephony Programming Model

The Telephony Application Programming Interface (TAPI) simplifies the development of telephonic applications by hiding the complexities of low-level communications programming. TAPI accomplishes this by abstracting telephony services to make them independent of the underlying telephone network and of the way the computer is connected to the switch and phone set. Connections to the switch may be established in a variety of arrangements including directly from the user's workstation or through a server on a local area network. Regardless of their nature, telephony devices and connections are handled in a single, consistent manner, allowing developers to apply the same programming techniques to a broad range of communications functions.


Telephony API

Telephony services are divided into Assisted Telephony services and the services provided by the full Telephony API. In general, the full Telephony API is used to implement powerful telephonic applications and Assisted Telephony is used to add minimal but useful telephonic functionality to non-telephony applications. Telephony's services are divided into the groups shown in the following illustration:


Assisted Telephony

A valuable feature of Win32 Telephony is the small set of functions called Assisted Telephony. Assisted Telephony is designed to make the establishment of voice calls and of media calls available to any Win32-based application, not just those dedicated to telephonic functionality. In other words, Assisted Telephony lets applications make telephone calls without needing to be aware of the details of the services of the full Telephony API. It extends telephony to word-processing applications, spreadsheets, databases, personal information managers, and other non-telephony applications. For example, adding the Assisted Telephony tapiRequestMakeCall function to a spreadsheet lets users automatically dial telephone numbers stored in the spreadsheet (or in a connected database).

The power of Assisted Telephony can be illustrated by the following example. A spreadsheet application can incorporate functions that dial a telephone number for a speech call. As long as the application needs none of the detailed call control provided by the full Telephony API, Assisted Telephony is the easiest and most efficient way to give it telephonic functionality. Functionality beyond dialing such as the transmission and reception of data would require additional data-transfer APIs, including the communications functions of the Comm API.

Because Assisted Telephony and the full Telephony API are used and implemented in different ways, it is not advised to mix Assisted Telephony function calls and Telephony API function calls within a single application.

For more information about the uses and functions of Assisted Telephony, see Assisted Telephony Overview.


Service Levels

Applications whose telephony functionality goes beyond the most basic call control or are meant to handle incoming calls must be built using the Telephony API (not Assisted Telephony). The Telephony API defines three levels of service:

  • The elementary level of service, called Basic Telephony, which provides a minimum set of functions that corresponds to Plain Old Telephone Service (POTS). TAPI service providers are required to support all Basic Telephony functions.
  • The Supplementary Telephony level of service, which provides advanced switch features such as hold, transfer, and so on. All supplementary services are optional; that is, the service provider is not required to support them.
  • The Extended Telephony level of service, in which the API provides well-defined API extension mechanisms that enable application developers to access service provider-specific functions not directly defined by the Telephony API.


Basic Telephony Services

Basic Telephony Services are a minimal subset of the Win32 Telephony specification. Because all service providers must support the functions of Basic Telephony Services, applications that use only these functions will work with any TAPI service provider. The functionality contained in Basic Telephony roughly corresponds to the features of POTS.

Today, many programmers will use only the services provided by Basic Telephony. But others, such as those writing code for PBX phone systems, will need the functions of Supplementary Telephony. Soon, the demand for ISDN and other network services, along with advancements in telephone equipment, will drive even greater usage of Supplementary Telephony.

For a list of the functions of Basic Telephony, see TAPI Quick Function Reference.

Because control of phone devices is not assumed to be offered by all service providers, phone-device services are considered to be optional. That is, they are not a part of Basic Telephony. For a list of phone-device services, see Supplementary Telephony Services; for more information on phone devices, see TAPI Device Classes.


Supplementary Telephony Services

Supplementary Telephony Services are the collection of all the services defined by the API other than those included in the Basic Telephony subset. It includes all so-called supplementary features found on modern PBXs, such as hold, transfer, conference, park, and so on. All supplementary features are considered optional; that is, the service provider decides which of these services it does or does not provide.

An application can query a line or phone device for the set of supplementary services it provides using functions such as lineGetDevCaps or lineGetAddressCaps. A single supplementary service may consist of multiple function calls and messages. The Telephony API, and not the service provider developer, defines the behavior of each of these supplementary features. A service provider should provide a Supplementary Telephony service only if it can implement the exact meaning as defined by the API. If not, the feature should be provided as an Extended Telephony service.

As mentioned in Basic Telephony Services, phone-device services are considered optional. Therefore, all phone-device services are part of Supplementary Telephony. For a list of the functions of Supplementary Telephony, see TAPI Quick Function Reference.


Extended Telephony Services

The API contains a mechanism that allows service-provider vendors to extend the Telephony API using device-specific extensions. Extended Telephony Services (or Device-Specific Services) include all extensions to the API defined by a particular service provider. Because the API defines the extension mechanism only, the definition of the Extended-Telephony Service behavior must be completely specified by the service provider.

TAPI's extension mechanism allows service-provider vendors to define new values for some enumeration types and bit flags and to add members to most data structures. The interpretation of extensions is keyed off the service provider's extension identifier, an identifier for the specification of the set of extensions supported, which may cross several manufacturers. Special functions and messages such as lineDevSpecific and phoneDevSpecific are provided in the API to allow an application to directly communicate with a service provider. The parameters for each function are also defined by the service provider.

Vendors are not required to register in order to be assigned extension identifiers. Instead, a utility called EXTIDGEN (extidgen.exe) is provided within the Microsoft Platform SDK that allows the local generation of extension identifiers. This unique identifier is composed of an Ethernet-adapter address, a random number, and the time of day. An identifier is assigned to a set of extensions (before distribution), not to each individual instance of an implementation of those extensions.


Extending Data Structures and Types

A range of values is reserved to accommodate future extensions to the Basic and Supplementary TAPI function set. For information about the amount by which a data structure can be extended, see Extensibility. For a list of the functions used for extending Telephony, see TAPI Quick Function Reference.


Version Parameters

Every function that takes a dwAPIVersion or similar parameter must set this parameter to either the highest API version supported by the application or the API version negotiated using the lineNegotiateAPIVersion or phoneNegotiateAPIVersion function on a particular device. Use the following table as a guide:

Function | Meaning
lineGetAddressCaps | Use version returned by lineNegotiateAPIVersion.
lineGetCountry | Use highest version supported by the application.
lineGetDevCaps | Use version returned by lineNegotiateAPIVersion.
lineGetProviderList | Use highest version supported by the application.
lineGetTranslateCaps | Use highest version supported by the application.
lineNegotiateAPIVersion | Use highest version supported by the application.
lineNegotiateExtVersion | Use version returned by lineNegotiateAPIVersion.
lineOpen | Use version returned by lineNegotiateAPIVersion.
lineTranslateAddress | Use highest version supported by the application.
lineTranslateDialog | Use highest version supported by the application.
phoneGetDevCaps | Use version returned by phoneNegotiateAPIVersion.
phoneNegotiateAPIVersion | Use highest version supported by the application.
phoneNegotiateExtVersion | Use version returned by phoneNegotiateAPIVersion.
phoneOpen | Use version returned by phoneNegotiateAPIVersion.

Important When negotiating an API version, always set the high and low version numbers to the range of versions that your application can support. For example, never use 0x00000000 for the low version or 0xFFFFFFFF for the high because these values require that your application support all versions of TAPI, both past and future.


Device Classes in TAPI

Device classes simplify development by letting programmers treat devices that have similar properties in a similar manner. Real-world devices such as telephones, modems, and telephone lines belong to device classes. Applications access devices belonging to a given class using the same functions.

An application never needs to know which service provider controls which device.

Device classes help make TAPI extensible by providing a framework from which to classify and support new equipment.

Application developers should keep in mind the existence of other applications that share telephony services, as explained in Multiple-Application Programming.

There are two device classes: line device and phone device.

TAPI also defines two sets of functions and messages, one used for line devices and one used for phone devices.

The line device class is a device-independent representation of a physical line device, such as a modem. It can contain one or more identical communications channels (used for signaling and/or information) between the application and the switch or network. Because channels belonging to a single line have identical capabilities, they are interchangeable. In many cases (as with POTS), a service provider will model a line as having only one channel. Other technologies, like ISDN, offer more channels, and the service provider should treat them accordingly.

A service provider may allow an application to request that multiple channels be combined in a single call (as, for example, when ISDN "B" channels are combined into "H" channels) to give the call wider bandwidth, using a technique often referred to as inverse multiplexing. This added bandwidth enables the call to transmit more information at the same time. For most current telephonic purposes, inverse multiplexing is not necessary.

In POTS, it is normally necessary to assign one channel per line, but with ISDN, a line's channels are dynamically allocated when an application makes or answers a call. Because these channels have identical capabilities and are interchangeable, the application need not identify which channel is to be used in a given function call. Channels are owned and assigned by the service provider for the line device in a way that is transparent to applications. This channel management is a method of abstraction that eliminates the need to introduce the naming of channels by TAPI.

Just as a line device class is an abstraction of a physical line device, the phone device class represents a device-independent abstraction of a telephone set. TAPI treats line and phone devices as devices that are independent of each other. In other words, you can use a phone (device) without using an associated line, and you can use a line (device) without using a phone.

Service providers that fully implement this independence can offer uses for these devices not defined by traditional telephony protocols. For example, a person can use the handset of the desktop's phone as a waveform audio device for voice recording or playback, perhaps without the switch's knowledge that the phone is in use. In such an implementation, lifting the local phone handset need not automatically send an offhook signal to the switch.

This independence also allows an application to ring the local telephone in a manner that is independent of incoming calls. The capabilities of service providers are limited by the capabilities of the hardware and software used to interconnect the switch, the phone, and the computer. For detailed information about specific device classes, see TAPI Device Classes.


Addresses to Line Assignments

An address is the telephone number, complete with national or international codes, of a telephone, fax machine, or other device that can receive calls. Addresses can be dialed by a human or stored in an electronic directory for retrieval and use by a telephony application. For more complete information on address assignments, channels, and lines, see Line Devices Overview.

The local assignment of an address to a line (controlled in TAPI) takes place in the setup operation for the service provider. This can be done using the Control Panel to configure the service provider or by calling the lineConfigDialog function from within the application. On the local side of the central office, everything about a line is controlled by a service provider, such as whether there are multiple addresses and what these addresses are.

Usually, there is exactly one address per line, with the following exceptions:

  • Multiple Addresses with POTS In POTS, multiple addresses work only with systems that support distinctive ringing or are connected to a DID trunk. (DID—direct inward dialing—is an extra-fee service provided by the phone company.) With DID in a multiuser voice mail system, the dialed number is signaled to the system on the DID trunk before the call rings. This allows the system to play the called party's pre-stored announcement message and to store any incoming messages in the correct voice mail box.

    On a residential line with distinctive ringing service, different ringing patterns correspond to multiple numbers assigned to the same line.

  • Multiple Addresses with ISDN ISDN was designed to allow simultaneous multiple addresses by providing multiple channels, each of which can have its own address. On an ISDN network, call offering (which means a call-setup message has been sent from the switch) takes place before ringing, so the call can be redirected before it is answered. The lineAccept function means start ringing for ISDN. For POTS, it means that some application has accepted responsibility for the call and has presented it to the user.


Call Control

The developer's view of telephony is one in which telephone lines and phone sets are logically connected through TAPI. This logical connection also provides a point of termination for the telephone line. The physical connection can be made at the desktop, or at a LAN-based host or server, where a LAN protocol extends the connection of the phone lines or phone to the client application. TAPI uses a first-party call-control model on the logically terminated line as well as control of the associated phone device, if any.

Applications access TAPI services using a first-party call control model. This means that the application controls telephone calls as if it is an endpoint (the initiator or the recipient) of the call. The application can make calls, be notified about incoming calls, answer incoming calls, invoke switch features such as hold, transfer, conference, pickup, and park, and can detect and generate DTMF (Dual Tone Multi-Frequency) tones for signaling remote equipment. An application can also use TAPI functions to monitor call-related activities occurring in the system.

In contrast, third-party call control means that the controlling application does not act as an endpoint of the call. A third-party call-control model allows an application to establish or answer a call between any two parties—the application does not act as either of these parties.

A service provider may implement TAPI's line and phone functions by treating the set of all stations on the switch as a single line device to which multiple phone numbers are assigned. Each phone number on the line device maps to one of the stations on the switch—that is, calls passing through the switch can reach a local station by using its address (telephone number). The application can answer calls or make calls, selecting any one of the addresses on the line device as the origination number. Although the application appears to be the originating party, a call is actually established between the station whose address was selected by its originating number and the other party. However, this implementation is a type of third-party call control and is not a design goal of TAPI, which emphasizes first-party call-control applications.


Media Access

The media mode is the form in which data is transmitted on a line. The four main types of media mode are voice, speech, fax, and data. With TAPI, calls can be established independently of the call's media mode.

The media stream is the actual stream of information that travels on the line. Phone devices and calls on line devices are capable of carrying media streams. The TAPI line and phone device classes provide a wide range of control operations for these devices, but access to the media stream itself is not provided by TAPI. Instead, the application must use other APIs for the Win32 environments to access or manage these media streams. These APIs include the Waveform API, the Comm API, and the MCI (Media Control Interface). The Waveform API is used for multimedia programming, the MCI provides a high-level generalized interface for controlling media devices, and the Comm API is the set of communications functions provided by the Microsoft Platform SDK.

For example, for line devices, an application can use TAPI to establish a connection to another station. Once the connection is established, the application can then use the Waveform API (or the MCI Waveaudio API) on the associated device to play back (send) and record (receive) audio data over the connection. Similarly, if the connection's media stream is from a modem, an application would use the modem configuration extensions of the Comm API to control the media stream.

To provide TAPI and media-stream access to either a phone or a call on a line device, the service provider must implement both the Telephony SPI and the appropriate media stream SPI or DDI (device-driver interface). The service provider can support lines and phones simultaneously.

Because these device classes and media stream interfaces function independently of one another, coordination of their usage must occur at the application level. Multiple applications that share calls and media streams in nontrivial ways will likely need to coordinate their activities at the application level to prevent conflicting usage of TAPI and the media stream API in use. For more information on preventing conflicts, see Multiple-Application Programming.

TAPI reports changes in the type of media stream (voice, fax, data modem, and so on) to participating applications. This process is sometimes referred to as call classification. The mechanism used to determine the type of media stream is specific to the service provider. For example, a service provider may filter the media stream for energy or tones that characterize the media type, or it may use distinctive ringing, information exchanged in messages over the network, or knowledge about the caller or called ID to make this determination.

TAPI also provides limited support for control of the media stream on a call, particularly in server-based networks. The actual data does not pass through TAPI, but TAPI can be used to a limited extent to control functions that control the media stream. This control is provided to avoid latency (delay) problems that could arise in client/server configurations for which the application is forced to use the stream's media API. An application can request actions on a call's media stream if these actions are to be triggered by events normally reported by TAPI, such as the detection of a tone or DTMF digit, or the transition of a call to a specified call state.

For example, an application can request that a call's media stream be suspended (with lineSetMediaControl) when a # DTMF digit is detected on the call, and that the media stream be resumed when a * DTMF digit is detected. Some implementations or configurations will be unable to provide any media-control functions or media access to the phone or line. Providing media control is optional to the service provider; it should provide performance benefits primarily for client/server implementations. Because it is optional and because only limited control is provided, its usage is generally discouraged. If possible, applications should use the media stream's control functions instead.


Application Notifications

The programming model for Win32 Telephony matches the standard programming model for the Win32 environment with regard to device naming, the use of the registry, and function calling conventions. But it deviates from this model in one important way—the synchronous/asynchronous operational model, which is a callback scheme through which applications are notified of the success or failure of function calls and other events.


Application Message Notification Mechanisms

TAPI version 2.0 and later support three mechanisms for notifying applications of changes in the status of calls, lines, and phones: a callback function, Win32 events, and completion ports. For detailed descriptions of these mechanisms, see lineInitializeEx and phoneInitializeEx.

Prior to TAPI version 2.0, only one such mechanism existed: the callback function. When the callback mechanism is used, the application's callback function is invoked from within the application's thread (at the time the application calls the GetMessage function), providing a normal, fully functional execution environment in which all Win32 APIs can be safely invoked.

A LINE_REPLY or PHONE_REPLY (asynchronous completion) message sent to the application carries the request identifier and an error indication. Valid error indications for this reply are identical to those that are returned synchronously for the associated request, or zero for success. Only the application that issued the request will receive the reply message, but when the request causes changes in the state of the device or call, other interested applications may also receive event-related messages.

TAPI guarantees that a reply message is made for every request that operates asynchronously, unless the application shuts down TAPI (by calling lineShutdown or phoneShutdown) before the reply is received.


Information Returned by Functions

An application receives two kinds of information as a result of a function call: the function's return value, and values written to data locations specified by the function's arguments.

If the function's return value is zero, the application knows that the function has completed synchronously. In this case, any values written as a result of the function call are reliable and can be used immediately. However, if the return value is positive, the function has not yet completed but it will complete asynchronously, at which time TAPI notifies the application by sending it an asynchronous reply message for the function. Once the application receives this message (and the message indicates success), any values returned by the function are considered to be reliable. However, before the message is received, the application should consider these values suspect and should not use them. Also, because asynchronous reply messages can take varying lengths of time to be sent, the application may not receive them in the same order in which it called their functions. This is why an application must retain the request identifiers of its requests in progress so that it can identify and correctly respond to incoming asynchronous reply messages.


Example Illustrating the Programming Model

Consider a Win32-based application that can make either voice or data (modem) calls. Although these calls could be made simultaneously if a telephone line were in place for each device (the telephone and the modem), assume that there is only one line, so calls are placed one at a time.

For this discussion, a line is defined as a physical telephone line leading from the wall to the telephone company's switch, and a line device (such as a fax or modem) is a local device on the telephone line. Also, this example is restricted to POTS; the telephone line is a standard, two-wire twisted-pair cable that carries an analog signal and constitutes a single channel.

The line devices attached to the computer are visible to the application as instances of the line device class, which is defined by TAPI. The physical telephone is visible to the application as an instance of the phone device class. This application therefore must be able to execute two types of calls: voice and data. One strength of the TAPI programming model is the way its abstraction into classes exploits the similarities between these different types of calls.

For a more in-depth discussion of this process and related ones, see TAPI Applications.


Determining the Call Type (Media Mode)

Before an application uses any telephony services, it needs to interact with the user to know what kind of call to make. To do this, the standard Win32 API functions are used to build the menus or dialog boxes needed to gather the user input that tells your application what to do. In this example, the user specifies the transmission of data, so the application will make a call that transmits a specified file to another user.


Initializing TAPI

Before placing a call, an application must establish a means of communication between itself and TAPI. The application must select a telephony event notification mechanism, and specify this in a call to the lineInitializeEx function. One of the values lineInitializeEx returns is the number of line devices available to the application. In this example, that number is one, and the line's identifier in telephony's zero-based scheme is 0. The application must establish this communication link (with lineInitializeEx) regardless of the type of call to be placed or received.


Obtaining a Line

Next, the application needs to obtain a handle to a capable telephone line. The application opens the line with lineOpen, but before doing this, it must make sure that the line can support the desired type of call. Invoking the lineGetDevCaps function returns that information to the application in a data structure of type LINEDEVCAPS. If data calls were not supported, this fact could be reported to the user in a dialog box. The application does not need to use lineGetDevCaps before every call, because a line's capabilities should remain static. If the local telephonic configuration (as expressed in .ini files) changes, TAPI notifies applications, which can then call lineGetDevCaps to see what has changed.

One of the values returned by lineGetDevCaps (as a member in the LINEDEVCAPS structure) is the number of addresses assigned to the specified line device. In this example, a single device has a single address.

Ownership of a call is a type of privilege. Applications obtain owner or monitor privilege to new incoming calls by specifying the desired privilege as a parameter of lineOpen. The privilege with which a line is opened remains in effect for subsequent calls used by that application on that line. An application always has owner privileges on calls it creates. When the application opens a line to place calls (as opposed to taking incoming calls) it invokes lineOpen with the privilege LINECALLPRIVILEGE_NONE, which insulates the application from incoming calls while allowing outgoing calls. The other privileges used with the lineOpen function are only for incoming calls.

The LINEOPENOPTION_SINGLEADDRESS option is available when using the lineOpen function to allow the application to specify that handles for new calls (either monitor or owner handles) should be delivered to the application only if the address on which the call appears matches the address provided as a function parameter. This is extremely useful when different addresses on a line are designated for calls of different media modes.


Placing the Call

Once the application has opened the line device, it places the call with lineMakeCall, specifying the address (phone number and area code) in the lpszDestAddress parameter and the media mode (datamodem, in this case) in the lpCallParams parameter. This function returns a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Negative return values describe specific error states. LINEERR_CALLUNAVAIL, for example, means that the line is probably in use (someone else already has an active call). If dialing completes successfully, messages are sent to the application to inform it about the call's progress. Applications typically use these messages to display status reports to the user.

Later, when the lineMakeCall function has successfully set up the call, the application receives a LINE_REPLY message (the asynchronous reply to lineMakeCall). At this point there is not necessarily a connection to the remote station, just an established call at the local end—perhaps indicated by a dial tone. This LINE_REPLY message informs the application that the call handle returned by lineMakeCall is valid.

TAPI's programming model treats data calls similarly to voice calls, as shown by the fact that the same function is used to make calls of both types. If LINEBEARERMODE_DATA is specified in a field of the lpCallParams parameter of lineMakeCall, the call is set up to send data. Speech transmission can be chosen by using a different value. And if NULL is specified, a default 3.1 kHz voice call is established, which can support the speech, fax, and modem media modes.

Note TAPI should not be used for fax transmissions. Instead, use the functions available through MAPI, the Microsoft Messaging API.

As the call is placed, it passes through a number of states, each of which results in a LINE_CALLSTATE message sent to the application. These states include dialtone, dialing, ringback, and, if connection succeeds, LINECALLSTATE_CONNECTED. (To see the complete list of call states, see LINECALLSTATUS.) After the message indicating the connected state is received, the application can begin sending data.


Sending Data

If the line is available (not busy) and the connection is established, the data can be sent. The application accomplishes this by giving control back to the user, who, using a dialog box, specifies the file to send and initiates data transmission. Though TAPI functions continue to manage the opened line and the call in progress, actual transmission is started and controlled by non-TAPI functions. In this case, for example, the Comm API of the Microsoft Platform SDK could be used to control the media stream.

If the application were setting up a speech call, its actions would be similar. Once the call is established, the duty of data transmission is transferred outside of TAPI to the people who want to speak, although the line and call continue to be monitored by the application using TAPI functions.


Ending the Call

When the modem transmission is finished, the application receives a LINE_CALLSTATE message, which informs it that the state of a line device has changed. In this example, a remote disconnect has occurred. The application disconnects the call at the local end (it "goes on-hook") with lineDrop. Alternatively, the application itself may choose to end the call by invoking lineDrop before receiving the remote-disconnect message.

Here are the steps that might be used to end a call, close the line, and leave TAPI:

  1. The application calls lineDrop, which places the call in the IDLE state. The call still exists, and the application still has its handle. Now the application can examine the call-information record, if desired.
  2. The application calls lineDeallocateCall to release the call handle for the finished call. The call no longer exists.
  3. If the application expects no more calls on the line, it uses lineClose to close the line. At this point, there will be no more incoming or outgoing calls on that line.
  4. The application invokes lineShutdown to end the use of TAPI's functions for the current session.


Synchronous/Asynchronous Operation

The interactive nature of telephony requires that TAPI be a real-time operating environment. Many of TAPI's functions are required to complete quickly and return their results to the application synchronously. Other functions (such as dialing) may not be able to complete as quickly and therefore operate asynchronously. Any given operation always completes either synchronously or asynchronously, and both types of operation are explained in the following topics. A list of all TAPI functions, which states whether each one completes synchronously or asynchronously, appears in TAPI Quick Function Reference.


Synchronous Functions

An operation that completes synchronously performs all of its processing in the function call made by the application. The function returns different values depending on its success or failure:

  • Synchronous Success. If the request or service corresponding to the function has been carried out successfully, the function returns zero, indicating success. Any values written as a result of the function call are reliable and can be used immediately.
  • Synchronous Failure. If the function detects an error and the request is not carried out, a negative error number is returned to identify the error.


Asynchronous Functions

An operation that completes asynchronously performs part of its processing in the function call made by the application and the remainder of it in an independent execution thread after TAPI has returned from the function call. To ensure completion of the call's processing, the service provider vectors the request to another active entity in the system—such as a LAN server, add-in hardware, a switch, or a network—and then returns to the application. At this time, either a negative error result or a positive request identifier is returned to the application.

At the time of asynchronous completion (the service provider has received an interrupt from the hardware, meaning that a message must be delivered), the service provider calls tapisrv.exe and reports that "Event X has just taken place. Deliver an appropriate message to all concerned applications." When tapisrv.exe receives this message, it forwards the message to the TAPI dynamic-link library, in the application's process, which in turn posts a window message, signals an event handle, or posts to an I/O completion port, according to the message notification scheme selected by the application in lineInitializeEx or phoneInitializeEx.

When the asynchronous portion of the operation completes, a LINE_REPLY (or PHONE_REPLY) message is sent to the application. This message contains, as one of its parameters, the request identifier returned by the function call. This request identifier allows the application to determine which original request has completed. (Applications should remember the request identifiers of all their requests in progress so that reply messages can be properly handled.) A second parameter to the LINE_REPLY (or PHONE_REPLY) message is the asynchronous return value. This is either a negative value (for an error) or zero if the operation completed successfully. For asynchronous operations, any of the return values may be returned as part of the function return or as the dwParam2 parameter in the LINE_REPLY or PHONE_REPLY message. The value 0, which indicates success, will only be returned in the LINE_REPLY message, and never as the function's return value.

The initialize functions (lineInitializeEx and phoneInitializeEx) tell TAPI how to send these messages to the application.

Note In some cases, if a multithreaded application calls an asynchronous function from a thread other than the thread from which the application initialized the line or phone device, the application may receive the LINE_REPLY or PHONE_REPLY message before the asynchronous function has returned. In such cases, the application should save the message parameters and wait until the asynchronous function returns and the request identifier is known before processing the message.


The Meaning of SUCCESS

When an operation returns a SUCCESS indication (either synchronously upon function return for synchronous operations, or asynchronously through a LINE_REPLY or PHONE_REPLY message for asynchronous operations), the following is assumed to be true:

  • The function has successfully progressed to a point that is defined by the API on a function-by-function basis. After that point has been reached, either the operation is completely finished, or it will be in a state such that independent state messages will inform the application about subsequent progress.

    For example, a service provider's implementation of lineMakeCall should return SUCCESS no later than when the call enters the proceeding call state. Ideally, the provider should indicate SUCCESS as soon as possible, such as when the call enters the dial tone call state (if applicable). Once SUCCESS has been returned to the application, LINE_CALLSTATE messages will inform the application about the progress of the call. Service providers that delay returning the lineMakeCall SUCCESS indication, for example, until after dialing is complete, must be aware that this places that provider at a disadvantage because the usability at the application level may be severely limited. For example, it would not be possible for a user to cancel the call setup request in progress until after dialing is complete and all digits had been sent to the switch.

  • Functions that return information (such as lineGetCallInfo) return SUCCESS only when the requested information is available to the application. Functions that return handles (to lines or calls), can return SUCCESS only after the handle is valid. No messages should be sent about that line or call prior to the SUCCESS indication of the function that caused its creation. The service provider is responsible for suppressing such messages.
  • Functions that enable certain permanent conditions (such as lineMonitorDigits) return SUCCESS only after the condition is enabled, not when the condition is removed again (for example, not when all digit monitoring has completed).
  • Call-control functions (such as lineHold or lineSetupTransfer, but not lineMakeCall) return SUCCESS when the operation is completed. Some telephone networks do not provide acknowledgment (positive or negative) about the completion of certain requests made by service providers. In such situations, the service provider must decide upon success or failure of the request. Therefore, SUCCESS may indicate that the service provider has initiated actions to fulfill the request, but not necessarily anything more. For example, the provider may receive no affirmative acknowledgment to its request from the switch, although it has already sent a success message to the application.


TAPI Applications

This section explains what you need to know to program basic telephonic functionality using the line device class functions.


Establishing a Link

Before an application can call the functions of Win32 Telephony for using a line device, it must take the following steps:

  • Initialize the TAPI environment and TAPI's functions with an initialization function. Invoking this function also informs the application of the number of line devices available.
  • Negotiate the API version, and if necessary, negotiate the Extensions version.

An application must take the preceding steps for each line device it intends to use.

Applications should not invoke phoneInitializeEx without subsequently opening a phone (at least for monitoring). If the application is not monitoring and not using any devices, it should call phoneShutdown so that memory resources allocated by the TAPI dynamic-link library can be released if unneeded, and the library itself can be unloaded from memory while not needed.


Opening Lines

After having obtained the capabilities of a line, an application must open the line device before it can access telephony functions on that line. (Because a line device is an abstraction of a line as defined by telephony, opening a line and opening a line device can be used interchangeably.) When a line device has been opened successfully, the application receives a handle for it. The application can then use that line to take incoming calls, make outgoing calls, or monitor call activities on the line for logging purposes.

To open a line device for any purpose—monitoring or control—the application calls the lineOpen function. (Later, when the application is finished with the line device, it can close it with lineClose.)

The lineOpen function can be invoked in one of two ways:

  • Specifying the line device. A specific line device is selected by means of its line-device identifier (the dwDeviceID parameter). The lineOpen request will open the specified line device. Applications interested in handling incoming calls typically use specific line devices because the application has been notified which line is carrying or is expected to carry the incoming call. When a line device has been opened successfully, the application is returned a handle representing the open line.
  • Specifying desired properties of any line device. The application can specify that it wants to use any line device that has certain properties. In this case, the application uses the value LINEMAPPER instead of a specific line-device identifier as a dwDeviceID parameter for lineOpen. The application also specifies which properties it needs on the call in parameters to lineOpen. The function opens any available line device that supports the specified call parameters. This attempt, of course, may fail. If successful, the caller can determine the line-device identifier by calling lineGetID, specifying the handle (lphLine) to the open line device returned by lineOpen.

An application that has successfully opened a line device can use it to make an outgoing call except when the line supports only incoming calls.


Selecting One or More Lines

An application can open one or more lines for various purposes. For example, it can open one line for monitoring calls and another line for making outgoing calls. If several lines are available, the application can choose to open any or all of them. To decide which of several line devices to use, determine the capabilities of each one with lineGetDevCaps. This function tells whether the line supports the functionality needed by the calls to be made or received, such as their required media mode. This function is also used to get the name of the line.

Because opening a line merely means obtaining a handle to the line (hLine) with a given privilege, an application can obtain more than one handle to the same line. In other words, an application can open the same line many times, also called opening different instances of the line. For example, a line may simultaneously be opened once for monitoring calls, a second time for accepting incoming calls as their owner, and a third time for making outgoing calls.

After choosing a suitable line (or lines), the application uses lineOpen, either specifying a certain line or using LINEMAPPER, as explained in Opening Lines.


Specifying Media Modes

The ability of an application to deal with incoming calls or to be the target of call handoffs on a line is determined by the value used for the dwMediaModes parameter of the lineOpen function. With this function, the application indicates its interest in monitoring calls or receiving ownership of incoming calls of one or more specific media modes, or of any (unspecified) media mode, as described in the following cases:

  • An incoming call of a certain media mode is given to the application that has opened the line device for that particular media mode. A single application may specify multiple flags simultaneously to handle multiple media modes.
  • An application that wants to handle calls for which the actual media mode present has not yet been determined would turn on the unknown media bit as a parameter of lineOpen.
  • An application that wants to handle calls of any media mode would indicate this capability by turning on all of the media bits that are supported on the line (which can be obtained from LINEDEVCAPS).

All applications that have opened a line device in any mode are notified about certain general statuses and events occurring on the line device or its addresses. These include the line being taken out of service, the line going back into service, the line being under maintenance, an address coming in use or going idle, and an open or close operation being executed on the line. An application that does not care about a certain message can use the lineSetStatusMessages function to filter the message. Most such status messages are disabled by default; an application would need to call lineSetStatusMessages to enable them.

The media modes specified with lineOpen add to the default value for the provider's media mode monitoring for initial incoming call type determination. This means that the dwMediaMode settings of all applications with the line open are ORed together, and that union becomes the default media detection on the line. The lineMonitorMedia function modifies the mask that controls LINE_MONITORMEDIA messages but does not affect the default media detection enabled on new incoming calls. It is necessary for an application using lineMonitorMedia to call it to establish media monitoring on every new call in which it is interested.


Requesting Call Privileges

In addition to media mode, an application can specify the call privileges it wants for the calls provided to it. With privileges, an application specifies whether it wants to monitor calls or own them. For an incoming call, only one application is selected as the owner, although all applications with monitor interest in the call are also notified about the incoming call. The usual privileges an application specifies are summarized in the following list:

  • If the application only wants to monitor calls, it specifies LINECALLPRIVILEGE_MONITOR. The application will also receive monitor handles to outgoing calls placed by other applications (an application receives owner handles for outgoing calls it places itself). It will also receive MONITOR handles for calls it places itself on other instances of the same line.
  • If the application wants to make outgoing calls only, it specifies LINECALLPRIVILEGE_NONE. An application that has NONE selected will not be automatically informed of incoming calls. However, it can also become aware of calls on the line with LINE_ADDRESSSTATE(numCalls) or LINE_LINEDEVSTATE(numCalls) messages. It can then call lineGetNewCalls.
  • If the application wants to accept incoming calls of a specific media mode (or modes), it specifies LINECALLPRIVILEGE_OWNER and one or more relevant LINEMEDIAMODE_ settings.
  • If the application is willing to control unclassified calls (incoming calls of as-yet unknown media mode), it specifies LINECALLPRIVILEGE_OWNER and LINEMEDIAMODE_UNKNOWN.
  • In other cases, the application should specify the media mode it is interested in handling and set dwPrivilege to LINECALLPRIVILEGE_OWNER.

An application that wants to be informed of all calls on the line regardless of whether it can become an owner on the call can set both the LINECALLPRIVILEGE_OWNER and LINECALLPRIVILEGE_MONITOR bits. It will get call handles with owner privileges for incoming calls for which it is the highest priority application for the highest priority media mode on the call, and monitor privileges for all other incoming and outgoing calls.

An application that has successfully opened a line device can always initiate calls using lineMakeCall, lineUnpark, linePickup, lineSetupConference (with a NULL hCall parameter), as well as use lineForward (assuming that doing so is allowed by the device capabilities, line state, and so on).


Application Priority

Conflicts can arise if multiple applications open the same line device for the same media mode. These conflicts are resolved with a priority scheme by which the user assigns relative priorities to the applications. This is usually done through a Control Panel utility or a Preferences menu in a telephonic application. Note the following points about this mechanism:

  • Only the highest priority application for a given media mode ever receives ownership (unsolicited) of a call of that media mode.
  • Although ownership is usually received when an incoming call first arrives or when a call is handed off, any application (including a lower priority one) can later acquire ownership by using the lineGetNewCalls or lineGetConfRelatedCalls function.

The user can assign relative priorities to the modules (the applications and the DLLs) that use TAPI. The resulting configuration information is stored in the registry.

For in-depth information about the way applications receive calls in a multi-application environment, see Multiple-Application Programming.


Using lineOpen

An application can open a number of lines as well as negotiate API and extension versions. The application can call the lineOpen function with LINECALLPRIVILEGE_MONITOR privilege, meaning that it will only monitor, not own, incoming calls on all the lines opened.

An application could open a line with the intent of owning incoming calls by specifying LINECALLPRIVILEGE_OWNER as the privilege and a media mode other than NONE. The application could actually specify a number of media modes in this parameter by OR-ing the bit flags for each of the desired media modes. In that case, the application would be notified of incoming calls in any of the specified media modes, and it receives those calls as their owner. (Actually, another application that is also registered to receive calls of that media mode would receive the call instead, if it has a higher priority as designated in the registry.) This notification arrives in a call-state message that specifies, among other information, which line is carrying the incoming call. For example, by specifying LINEMEDIAMODE_INTERACTIVEVOICE, the application would be notified of incoming calls of the interactive voice media type (voice calls with a person on the local end of the line).


Receiving Information

An application receives information in two ways: solicited and unsolicited. Solicited information is requested by the application through a function call such as lineGetDevCaps or lineGetAddressCaps. Unsolicited information arrives in the form of messages—most importantly call-state messages. Often, the two mechanisms are used together, as when an application receives a LINE_CALLSTATE message, after which it checks the information contained in the LINECALLINFO structure by calling lineGetCallInfo.

An application can call lineGetDevCaps to learn more about available lines. The application determines the names of the lines and the number of addresses on those lines. (An important factor in the configuration of lines and addresses is the way the service provider chooses to map lines and addresses. Though the application has no control over this mapping, it can determine the details of the mapping by calling functions such as lineGetDevCaps.) Later, using this information, the application could allow the user to choose which line (and address) to use for an outgoing call, restricting the lines it displays (in a dialog box, for example) to those that support a specific media mode. As an example, an application designed to be used only for faxing may choose to let the user select only lines that support fax transmission.

Call lineGetAddressCaps to obtain information for a given address. The application can use the names of the addresses to let the user choose them in a popup menu, but other information is also reported, such as whether caller-ID is supported, what kinds of call states can be produced, and how many active calls can exist on that address.


Changes in the Status of a Line Device

The status of a line device can change for many reasons, some as a result of requests submitted by the local application, and some as a result of actions performed by the switch or by the application (or person) at the other end of the connection.

In either case, an application is notified about these changes with the LINE_LINEDEVSTATE message, which indicates the status item (the attribute of the line device) that has changed. The application can choose the line status items for which it wants to be notified using the lineSetStatusMessages function. The messages controlled by invoking lineSetStatusMessages are LINE_LINEDEVSTATE and LINE_ADDRESSSTATE.

In addition, an application can determine the current status of an address by calling lineGetAddressStatus, which returns its information in a structure of the type LINEADDRESSSTATUS. It can also see the complete status of the specified open line device by calling lineGetLineDevStatus, which returns its information in a structure of the type LINEDEVSTATUS.


Receiving Calls

After an application has opened a line device and, while doing so, registered a privilege other than none, and a media mode, it is notified when a call arrives on that line. Specifically, applications that have the line open with LINECALLPRIVILEGE_MONITOR will receive a LINE_CALLSTATE message for every call that arrives on the line. An application that has opened the line with LINECALLPRIVILEGE_OWNER receives a LINE_CALLSTATE message only if it has become an owner of the call or is the target of a directed handoff. In this notification, TAPI gives the application a handle to the incoming call, and the application keeps this handle until the application deallocates the call.

Note To assist in object-oriented implementations of TAPI, in versions 2.0 and later TAPI initially sends a LINE_APPNEWCALL message (instead of a LINE_CALLSTATE message) to the application to notify it of a new call handle.

Applications are informed of call arrivals and all other call-state events with the LINE_CALLSTATE message. This message provides the call handle, the application's privilege to the call, and the call's new state. For an unanswered incoming call, the call state is offering. An application can invoke lineGetCallInfo to obtain information about an offering call before accepting it. This function call also causes the call information in the LINECALLINFO data structure to be updated. By knowing the call state and other information, the application can determine whether the call needs to be answered.

The call information stored in LINECALLINFO includes, among other things, the following items:

  • Bearer mode, rate This is the bearer mode (voice, data) and data rate (in bits per second) of the call, for digital data calls.
  • Media mode The current media mode of the call. Unknown is the mode specified if this information is unknown, and the other set bits indicate which media modes might possibly exist on the call. For more information, see Multiple-Application Programming.
  • Call origin Indicates whether the call originated from an internal caller, an external caller, or an unknown caller.
  • Reason for the call Describes why the call is occurring. Possible reasons are:
    • Direct call
    • Transferred from another number
    • Busy—forwarded from another number
    • Unconditionally forwarded from another number
    • The call was picked up from another number
    • A call completion request
    • A callback reminder

    The reason for the call is given as unknown if this information is not known.

  • Caller-ID Parameter that identifies the originating party of a call. This can be in a variety of (name or number) formats, determined by what the switch or network provides.
  • Called-ID Parameter that identifies the party originally dialed by the caller.
  • Connected-ID Parameter that identifies the party to which the call was actually connected. This may be different from the called party if the call was diverted.
  • Redirection-ID Parameter that identifies to the caller the number to which the call is now diverted (redirected).
  • Redirecting-ID Parameter that identifies to the caller the original destination from which the call was diverted (redirected).
  • User-user information User-user information sent by the remote station (ISDN).

The LINE_CALLSTATE message also notifies monitoring applications about the existence and state of outgoing (and incoming) calls established by other applications or established manually by the user—for example, on an attached phone device (if the telephony hardware and the service provider support monitoring of actions on external equipment). The call state of such calls reflects the actual state of the call as follows: An incoming call for which ownership is given to another application is indicated to the monitor applications as initially being in the offering state. An outgoing call placed by another application would normally first appear to the monitoring applications in the dialtone state.

The fact that a call is offered does not necessarily imply that the user is being alerted. Once alerting (ringing) has begun, a separate LINE_LINEDEVSTATE message is sent with a ringing indication to inform the application. It may be necessary, in some telephony environments, for the application to accept the call (with lineAccept) before ringing starts. The application can determine whether or not this is necessary by checking the LINEADDRCAPFLAGS_ACCEPTTOALERT bit.

Depending on the telephony environment, not all the information about a call may be available at the time the call is initially offered. For example, if caller ID is provided by the network between the first and second ring, caller ID will be unknown at the time the call is first offered. When it becomes known shortly thereafter, a LINE_CALLINFO message notifies the application about the change in party-ID information of the call.


Incoming Calls and Line Privileges

An application cannot refuse ownership of a call for which it receives an owner handle. Whether the call is delivered to the application with owner or monitor privileges is decided before the call arrives—at the time the application opens the line on which the call is established by the remote caller.

If the application opens the line with lineOpen with the dwPrivilege parameter set to LINECALLPRIVILEGE_MONITOR, it automatically receives a handle with monitoring privileges for all incoming calls on the line. It can then choose to become an owner by calling lineSetCallPrivilege. The fact that it indicated LINECALLPRIVILEGE_MONITOR when it opened the line does not prevent it from later becoming an owner with lineSetCallPrivilege or by originating a call with lineMakeCall (an application is always an owner of calls it places regardless of the privilege specified with lineOpen).

When an incoming call has been offered to an application and the application is an owner of the call, the application can answer the call with lineAnswer. Once the call has been answered, its call state typically transitions to connected, at which time information can be exchanged over the call.

An application can receive handles to incoming calls only for monitoring. You can modify the application (specifically, the parameters for lineOpen) to change the privileges with which it initially opens lines.


Securing a Call

If a new call arrives while another call exists on the line or address, similar notification and call information may be supplied following the same mechanism as for any incoming call. If an application does not want any interference by outside events for a call from the switch or phone network, it should secure the call. Securing a call can be done at the time the call is made with a parameter to lineMakeCall, or later (when the call already exists) with lineSecureCall. The call will be secure until the call is disconnected. Securing a call may be useful, for example, when certain network tones (such as those for call waiting) could disrupt a call's media stream, such as fax.


Logging Call Information

An application can call the lineGetCallInfo function to obtain information about a call. Although this function fills the LINECALLINFO structure with a large amount of data, applications need to maintain other items, such as the start and stop time of the call.

Developers of applications that log call information should note the following guidelines when designing those applications:

  • Free the call's handle (hCall) when the call goes idle—that is, when a LINECALLSTATE_IDLE message is received for the call. At any point in the call's existence prior to its deallocation, monitoring applications can retrieve information about the call.
  • To keep the call's log sheet complete, log the fact that the call has gone idle.
  • Determines whether the application needs to update the user interface to show that important events have occurred, such as the fact that a fax is being received.

For more information about call logging, see Multiple-Application Programming.


Establishing a Call

Once an application has determined that a given line offers the needed set of capabilities, and then opens that line, it can access telephony functions for either incoming or outgoing calls on the line. The usual way to place a call on that line is to invoke lineMakeCall, specifying the line handle and a dialable destination address.


Address Translation

Applications can provide users with location independence and take advantage of calling-card information managed by Win32 Telephony by storing telephone numbers in the canonical address format. Before a Canonical address can be used in placing a call, it must be converted (translated) into the dialable address format using the lineTranslateAddress function.

To do this, the lineTranslateAddress function starts by examining the settings in the registry to find the user's location, including the country and area code. It then produces a valid dialing sequence by removing unnecessary portions of the number (such as the country code or area code) and adding other digits such as a long distance prefix or a digit used to dial out of a local PBX.

To avoid inadvertent misdialing, such as if the user has changed locations but has not yet informed Win32 Telephony of the change, an application may want to present the output of this function call to the user in a dialog box. The user can then confirm the translated address or change it if it is incorrect.


Toll Lists

In some locations in North America, all calls placed to the local area code are local calls. In other locations, some calls placed to the local area code are long distance, and need a "1" to be dialed. The first three digits of the address (the prefix) determine whether or not a call within the local area code is a toll call.

A toll list is a list of prefixes in the local area code whose addresses must be dialed as long distance addresses, and are assessed long distance charges. With Win32 Telephony, a toll list can be built in one of two ways:

  1. The user can add or remove prefixes manually with the Telephony Control Panel.
  2. The user can add or remove prefixes dynamically after a telephone call to that prefix fails for one of these reasons: When the call was dialed, the "1" prefix was missing and necessary or present and unnecessary. This dynamic process works as follows:

    The application knows by the value of the LINETRANSLATERESULT_INTOLLLIST and LINETRANSLATERESULT_NOTINTOLLLIST bits in the LINETRANSLATEOUTPUT structure (returned by lineTranslateAddress) whether an address with the dialed prefix is already in the toll list. The application can then let the user add or remove (whichever applies) this prefix from the toll list. Adding and removing of a prefix are both performed using the lineSetTollList function.


Dialing the Call

The lineMakeCall function first attempts to obtain a call appearance on an address on the line, then waits for a dial tone, and finally dials the specified address. A call appearance is a connection to the switch over which a call can be made. Once the connection is established, the call appearance exists, even if no call is placed. After the call is established, the call appearance remains in existence until the call transitions to the idle state. If calls controlled by other applications exist on the line, these calls would normally have to be on hold, and would typically be forced to stay on hold until the application either drops its call or places it on hold. If dialing is successful, a handle to a call with owner privileges is returned to the application.

Before invoking lineMakeCall, an application can set up parameters for the call and store them in the LINECALLPARAMS data structure. A pointer to this structure is then used as a parameter of lineMakeCall. In the members of LINECALLPARAMS, the application can specify the quality of service requested from the network, as well as a variety of ISDN call setup parameters. If no LINECALLPARAMS structure is supplied to lineMakeCall, a default POTS voice-grade call is requested with a set of default values. However, it is a good idea to use LINECALLPARAMS so that monitoring applications can report this call information (such as the identification of the called party) accurately.

The call's origination address also appears in LINECALLPARAMS. Using this field, the application can specify the address on the line where it wants the call to originate. It can do so by specifying an address identifier, though in some configurations it is more practical to identify the originating address by its directory number.

Note Do not mix function calls of TAPI with the those of Assisted Telephony because it creates needless repetition and additional overhead.

Once dialing is complete and the call is being established, it passes through a number of different states. These states (the progress of the call) are provided to the application with LINE_CALLSTATE messages. This mechanism lets the application track whether the call is reaching the called party. It is important that every telephony application base its behavior on the information received in these messages, and not on any other assumptions about a call's state. An application must not assume that a requested state change has occurred until notification of that state change arrives. It can be helpful to display user-friendly interpretations of call states as indicators of a call's progress, especially for calls expected to pass through states slowly.

If special call setup parameters are to be taken into consideration, the application must supply them to lineMakeCall. Call setup parameters are required for actions such as the following:

  • Requesting a special bearer mode, bandwidth, or media mode for the call
  • Sending user-user information (with ISDN)
  • Securing the call
  • Blocking sending of caller ID to the called party
  • Taking the phone offhook automatically at the originator and/or the called party


Calling Card Information

A calling card is a generic term for a credit card issued by a telephone company and used for charging local and long distance calls. Calling card information is data supplied during the progress of a call. Typically, the information required varies with the different dialing procedures required by the various calling cards.

An application provides TAPI with the information it needs to display a dialog box, from which the user can choose a calling card. (The calling card numbered 0 means "use the default dialing rules for the country you are in.") The routine returns, among other information, the user's location (country and area code), the number of calling cards registered for this user in the registry, and the preferred calling card for that location. This calling card information is applied by the lineTranslateAddress function and does not happen automatically through lineMakeCall.

Typically, an application would prepare a menu choice for the user, such as whether to make a call with the default carrier, to override the default carrier and use a given calling code, or simply to use another specific dialing sequence.


Using Multiple Addresses Simultaneously

The dialable number format allows multiple destination addresses to be supplied at once. (Dialing formats are described in Dialable Addresses.) This ability can be useful if the service provider offers some form of inverse multiplexing by setting up calls to each of the specified destinations and then managing the information stream as a single high-bandwidth media stream. The application perceives this group of calls as a single call because it receives only a single call handle representing the aggregate of the individual phone calls.

It is also possible to support inverse multiplexing at the application level. To do this, the application would set up a series of individual calls and synchronize their media streams.


Partial Dialing

In partial dialing, the application can use lineMakeCall to allocate a call appearance or to dial just part of the full number. Later, the application can complete dialing using lineDial. Partial dialing is sometimes referred to as incremental dialing or delayed dialing.

When the number provided is incomplete, dialing some of the digits may be delayed by placing a ";" (semicolon) at the end of the number. The lineDial function is used in cases in which the application needs to send address information to the switch on an existing call, such as dialing the address of a party to which the call will be transferred.

Note An application should make sure that incremental dialing (providing the number in small pieces) is supported before attempting to use it. This support is indicated by the LINEADDRCAPFLAGS_PARTIALDIAL bit in the dwAddrCapFlags member in the LINEADDRESSCAPS structure, which is returned by lineGetAddressCaps.

The main reasons for an application to use partial dialing are if the ? character appears in a dialable address or if the service provider does not support one or more of the call progress detection control characters. These characters, which can occur in a dialable address, are W (wait for dial tone); @ (wait for quiet answer); and $ (wait for calling-card prompt tone). These and all other characters used in address strings are discussed in greater detail in Dialable Addresses.

The provider indicates which "wait for" dial string modifiers it supports in the following bits in the dwDevCapFlags member within the LINEDEVCAPS structure returned by lineGetDevCaps:

  • LINEDEVCAPFLAGS_DIALBILLING
  • LINEDEVCAPFLAGS_DIALQUIET
  • LINEDEVCAPFLAGS_DIALDIALTONE

The ? can be placed in the string (either directly by the application or by the address translator with the lineTranslateAddress function) if it is known that the user needs to listen for an undetectable tone before dialing can proceed. Every service provider should reject a dial string that contains the ? character and let the application deal with it as appropriate. For example, the application could use partial dialing to dial the string, up to but not including the ? character, and then display a dialog to let the user signal when the rest of the dial string should be dialed.

The lineTranslateAddress function returns bits, in the dwTranslateResults member of the LINETRANSLATEOUTPUT structure, that indicate whether any of the four potentially offending modifiers occur in the dialable string output from that translation operation. These bits give the application an idea of whether the dialable string might need to be scanned for unsupported modifiers:

  • LINETRANSLATERESULT_DIALBILLING
  • LINETRANSLATERESULT_DIALQUIET
  • LINETRANSLATERESULT_DIALDIALTONE
  • LINETRANSLATERESULT_DIALPROMPT

If the application tries to send an unsupported modifier or a ? to the provider, it receives an error indicating which offending modifier occurred first within the string:

  • LINEERR_DIALBILLING
  • LINEERR_DIALQUIET
  • LINEERR_DIALDIALTONE
  • LINEERR_DIALPROMPT

The application can choose to pre-scan dialable strings for unsupported characters. Or it can pass the "raw" string from lineTranslateAddress directly to the provider as part of lineMakeCall (or lineDial or any other function that passes a dialable address as a parameter) and then let the service provider generate an error to tell it which unsupported modifier occurs first in the string.

When the application is told (or finds) that an unsupported dial modifier is in the dialable string, it must take the following steps:

  1. Locate the offending modifier in the string.
  2. Isolate the characters occurring in the string to the left of the offending modifier.
  3. Append a semicolon to the end of the partial string.
  4. Reissue the dialing command using the partial string.
  5. Prompt the user to listen for the audible tones indicating when it is OK to proceed with dialing.
  6. Reissue the remainder of the dialable string (the portion following the offending modifier).

    Note In step 6 it is possible for another error to occur, because it is possible for multiple unsupported characters to occur within a single dialable string. Therefore, the application should repeat this process to dial the number in stages.


Tracking Asynchronous Requests

The lineMakeCall function is one of many functions that operate asynchronously. If an application manages only one line, it can use one state record, a struct containing all the information needed to track one outstanding asynchronous request. State records contain information such as the request identifier, the type of request, and pointers to allocated data that may need to be freed later.

But some applications have to manage more than one line—for example, to manage more than one outgoing call at the same time. To do so, they need to track the different asynchronous requests possible on each of those lines, and must therefore create an array of state records, one for each of the outstanding asynchronous operations (such as multiple invocations of lineMakeCall).

When a reply arrives that shows an asynchronous function has completed, the application matches the incoming request identifier with a request identifier in the array, and does whatever that specific call needs at that point. You can design one function to handle the reply that indicates completion of the outstanding asynchronous lineMakeCall request. The success or failure of the asynchronous request is recorded in the requestResult field of the state struct.


Call Handle Manipulation

When an application makes a call, a handle to the call with owner privileges is returned to the application. When the application is notified about an incoming call, it is given a handle to the call with either owner privilege or monitor privilege, depending on the privilege previously requested with lineOpen. It can also receive a handoff from another application, in which case it would receive owner privilege.

An application's call handle and associated privileges remain valid until the application takes an explicit action to change them or if it receives a LINE_CLOSE message, which closes the line. In this case, all handles to calls on the line instantly become invalid.

After a call reverts to the idle state, the application is still allowed to read the call's information structure and status. When the application has no further use for the call (and its information), it should deallocate the call handle by invoking lineDeallocateCall, which is discussed in following topics.

For more information about call logging and handing off calls to other applications, see Multiple-Application Programming.


Dropping Calls

To terminate a call, the application uses lineDrop on the call. This has the effect of hanging up on (disconnecting) the call, which makes it possible to make another call on the line. The lineDrop function is also used to abandon a call attempt in progress. If the remote party disconnects a call, the local application receives a LINE_CALLSTATE message with a call state of disconnected. If the local application disconnects a call, the call becomes idle, but its handle is not automatically deallocated (the application must call lineDeallocateCall). An application should check the dwCallFeatures member in LINECALLSTATUS to determine whether or not it is acceptable to invoke lineDrop at a particular time.


Deallocating Call Handles

A call handle remains valid after the call has been dropped. This enables applications to use operations such as lineGetCallInfo to retrieve call information for logging purposes. Once an application knows it has all the information it needs about a call and it has received a LINE_CALLSTATE(LINECALLSTATE_IDLE) message, it should call lineDeallocateCall to free system-allocated memory related to the call. The application must itself free memory that it allocated for its own purposes.

The way to free an idle call is to deallocate its handle with lineDeallocateCall. The application's duty to free a call is independent of the reason the call went idle. That is, the handle must be deallocated whether it was the local or the remote application that dropped it. If an application is the owner of the call, it can deallocate the call's handle only if the call is in the idle state. If monitoring the call, it can deallocate the call handle at any time.

It is better to process the LINE_CALLSTATE(LINECALLSTATE_IDLE) message (and all other call-state notifications) consistently in one location regardless of its cause.


Reclaiming Memory Resources

The TAPI dynamic-link library allocates memory for each call for each application that has a handle to the call. It is likely that service providers will allocate memory to hold call information as well. Deallocation of an application's call handle allows the library and the service provider to reclaim these memory resources. An application's handle for a call becomes void after a successful deallocation.

An application's attempt to deallocate the handle of a non-idle call for which it is the only owner will fail. The application should either first hand off ownership and change its privilege to monitor, or simply try to change its privilege to monitor (in case there are other owners) or clear the call by dropping it, which places the call into the idle state, and then deallocate its handle.


Closing Line Devices

After an application is finished using a line device, it should close the device by calling lineClose on the line-device handle. After the line has been closed, the application's handle for the line device is no longer valid. A LINE_LINEDEVSTATE message is sent to other interested applications to inform them about the state change on the line.

In certain environments, it may be desirable for a line device that is currently open by an application to be forcibly reclaimed (possibly by the use of some control utility) from the application's control. This feature can be used to prevent a single misbehaved application or user from monopolizing a line. It is also used when the user wants to reconfigure the line parameters, and has told the service provider directly through its Setup function in the Telephony Control Panel that the provider should forcibly close the line. When this occurs, an application receives a LINE_CLOSE message for the open line device that was forcibly closed.


Exiting Telephony

The lineShutdown function disconnects the application from TAPI. If this function is called when the application has lines open or calls active, the call handles are deleted and the equivalent of a call to the lineClose function is automatically performed on each open line. (It is better for applications to explicitly close all open lines before invoking lineShutdown.) If shutdown is performed while asynchronous requests are outstanding, those requests are canceled.

An application that has registered as an Assisted Telephony request recipient should de-register itself by calling lineRegisterRequestRecipient, using the value FALSE for the bEnable parameter.


Setting a Terminal for Phone Conversations

The user's desktop computer may have access to multiple devices that can be individually selected and used to conduct interactive phone conversations. One of these devices is the telephone itself, complete with lamps, buttons, display, ringer, and a voice I/O device (handset, speakerphone, or headset). The user's computer may also have a separate voice I/O device (such as a headset, or microphone/speaker combination attached to a sound card) for use with phone conversations. TAPI enables the user to select where to route the information sent by the switch over the line, address, or call. The switch normally expects this destination to be one of its phone sets, and sends ring requests, lamp events (for stimulus phones), display data, and voice data as appropriate.

The phone in turn sends hookswitch events, button press events (for stimulus phones), and voice data back to the switch. The line portion of TAPI makes lamp events, display events, and ring events available, either as functional return codes to TAPI's various operations or as unsolicited functional call-status messages sent to the application. TAPI's implementation is responsible for mapping the functional API level to the underlying stimulus or functional messages used by the telephony network. In functional telephony environments, TAPI's functions are mapped to the functional protocol.


Modes of Operation: Functional and Stimulus

The functional mode of telephone operation differs from the stimulus mode in the way meaning is attributed to events. For example, a given telephone has a button labeled "Transfer." When this button is pressed, one of two things can happen: the phone can send a message to the switch stating that the Transfer button was pressed, or it can send a message stating that "button number 18" was pressed. In the functional model, the button's function is indicated. It allows more flexibility in the phone hardware, because the switch doesn't need to know anything about the layout of the buttons, but the telephone will likely be more expensive, because it has more intelligence.

The stimulus model means that the event is simply indicated in a more raw, hardware fashion, such as by button number—even down to separate button-up and button-down events. In a stimulus-based system, telephones can cost less, but more intelligence is required in the switch so that it can recognize different types of telephones and translate their buttons into features. The stimulus model can provide more flexibility because different people can configure their phone buttons to mean different things through switch programming rather than by changing the phone itself.


Event Routing

Although not described in Supplementary Line Functions, event routing is a part of the supplementary line services and is not a basic function.

With the lineSetTerminal function, the application can control or suppress the routing of specified low-level events (exchanged between the switch and the station) to a device. With lineSetTerminal, the application specifies the terminal device to which these events (such as line, address, or call media-stream events) are routed.

The routing of the different classes of events can be individually controlled, allowing separate terminals to be specified for each event class. Event classes include lamps, buttons, display, ringer, hookswitch, and media stream.

For example, the media stream of a call (voice, for example) can be sent to any transducer device if the service provider and the hardware is capable of doing so. In general, a transducer means the same as what is referred to as a hookswitch device in TAPI, something that has a microphone and a speaker. Ring events from the switch to the phone can be mapped into a visual alert on the computer's screen or they can be routed to a phone device. Lamp events and display events can be ignored or routed to a phone device (which appears to behave as a normal phone set). Finally, button presses at a phone device may or may not be passed to the line. In any case, this routing of low-level signals from the line does not affect the operation of the line portion of TAPI, which always maps low-level events to their functional equivalent. To determine the terminals a line device has available (and their capabilities), consult the line device's capabilities with lineGetDevCaps.

Assume initially that the application has suppressed the routing of all events (with lineSetTerminal), and the user selects a headset as the current I/O device. An incoming call sends a LINE_CALLSTATE message, and a LINE_LINEDEVSTATE message with the ringing indication. Because routing of all events is suppressed, ring events are not routed to the phone, so ringing is suppressed. Instead, the application notifies the user with a pop-up dialog box and a system beep in the headset.

The user decides to answer the call. Because the user's current I/O device is the headset, the telephony application invokes lineSetTerminal on the incoming call to route the call's media to the headset and answer the call. The application may also invoke lineSetTerminal to route lamp and display information events to the phone set so that it will behave as usual.

As a second example, assume that an incoming call is alerting at the user's computer. Instead of selecting the answer option with the mouse, the user decides to just pick up the phone's handset to answer the call. The offhook status at the phone sends a message to the application. The application can interpret this status as a request by the user to select the phone handset to conduct the conversation. The application then invokes lineSetTerminal to route the voice data on the call to the phone set.


Service Dependencies

Take care to ensure accurate listing of service dependencies among TAPI (specifically, the telephony service—tapisrv.exe), other service applications that use TAPI, and telephony service providers that use other services.

The installation program for the service application or telephony service provider must record these dependencies with the Service Control Manager.

Note Failure to list TAPI as a dependency of the service application or failure to list another service as a dependency of TAPI can result in the system hanging.

List "Telephony Service" as a dependency of any service application that initializes a TAPI line or phone function. When TAPI is a dependency of a service application, the installation program must include "Telephony Service" in the list of service names passed to the lpDependencies parameter of the CreateService function.

When another service is activated by the telephony service provider during the service provider startup (during TSPI_providerEnumDevices, TSPI_lineNegotiateTSPIVersion, or TSPI_providerInit), the service started by the telephony service provider must be listed as a dependency of the "Telephony Service." As a service that starts dynamically, TAPI starts all telephony service providers during its startup, and it is critical for the Service Control Manager to know when any service provider starts another service during telephony service provider startup.

Call the QueryServiceConfig function to determine the existing configuration of "Telephony Service", including dependencies. If the service or services started by the telephony service provider are not already included in the dependencies of the "Telephony Service", add the necessary items to the dependency list and call ChangeServiceConfig to update the dependencies.

For additional information about changing a service configuration, see the Microsoft Platform Software Development Kit.


Multiple-Application Programming

Win32 Telephony applications may be designed to cooperate with each other, or they may act independently of one another. These TAPI applications will at times operate with non-TAPI applications built to support TAPI functionality, such as media-stream control applications. All these applications must be able to work together, or at least function independently in a cooperative way. To achieve this, TAPI defines mechanisms that let applications coordinate their telephony and phone activities while maintaining a high degree of flexibility.

The roles played by telephony's major components are described in various topics of this section. Application writers can not only learn about TAPI's functioning from these sections, but can apply that knowledge directly when designing TAPI applications. For example, the unknown application (see Definitions) performs specific duties in media-mode probing and call handoffs. It is important to note and understand these duties before writing an unknown application.


Event-Driven Environment

Like all Win32 applications, Win32 Telephony applications operate in the event-driven model. In telephony, the most important events are call-state transitions. The service provider and TAPI dynamic-link library report call states to applications for particular calls. Interested applications, which know the previous state of the call, could infer call-state transitions from call states.

All running applications receive information—call-state messages—about all the calls in which they are interested. At times, several applications will have interest in the same call or calls, as monitors or owners of those calls. Incoming call-state events often cause applications to take actions on calls, and because those actions sometimes involve a shared call, one application must react to the knowledge that another has taken a certain step. Examples include the case where one application shows interest in owning (having control of) a call currently owned by your application, or drops a call co-owned by your application.

The telephony system was designed to minimize race situations—in which the timing of competing function calls from different applications makes a difference.


Definitions

The following concepts are important for understanding the material presented in this section:

  • Initial media modes On a network other than ISDN, service providers usually do not know the media mode of an arriving call. For such calls, the service provider indicates a number of initial media modes, from which the correct one is eventually selected during the next step—the probing process. The initial media mode(s) identified by the service provider as being possible on the call will be reflected in the dwMediaMode member of the LINECALLINFO data structure, which the application can obtain by calling lineGetCallInfo after the initial LINE_CALLSTATE message announcing a new call is received.
  • Call control Having control of a call means that the application has received a LINE_CALLSTATE message stating that it has become an owner of the call. With this event, the application acquires a handle to the call with owner privileges. A way for a monitoring application to obtain call control (ownership) is to call lineSetCallPrivilege to set its call privilege to owner.
  • Call monitor An application that has a handle to a call with monitor privileges is a monitor of that call. Such an application cannot control the existence or other aspects of the call, but it can record (log) facts about the call. The application can also reset its call privilege to owner, thus becoming an owner of the call, in the event that the application determines (by monitoring media modes or other events) that it should take control.
  • Call owner An application that has control of a call is an owner of that call. An application can become an owner of a call in several ways (see Call Ownership). A call can have several owners simultaneously, although the usual situation is for only one application to be the owner of a call.
  • Probing Probing is the sending of signals on the phone line as an attempt to determine an incoming call's media mode. This search for the media mode is conducted only by applications. Some service providers may also be configured to do some amount of probing automatically to narrow down the initial media modes reported on a new call.
  • The unknown application An application that has opened a line requesting ownership privilege for calls of as yet undetermined, or UNKNOWN media mode, is referred to as the unknown application. (The LINEMEDIAMODE_UNKNOWN bit is set in the dwMediaMode member of the LINECALLINFO structure, along with other bits indicating other modes that are potentially present on the call.) An application that does this may actually be capable of handling calls of a number of different media modes. Alternatively, it may simply act as a traffic director, passing calls on to other applications that can use calls of the specific media modes.


Call Ownership

The mechanism with which applications control calls is based on the concept of ownership. At any given time, one or more applications can own a call. While an application has ownership of a call, it is allowed to manipulate the call in ways that affect the state of the call. An application that does not own a call (but has a handle to it) is a monitor of the call and is prevented from manipulating it. It can only perform status- and information-query operations on that call. While one or more applications are owners of a call, still other applications can be monitoring the call.

Ownership of a call is assigned to applications according to the following rules:

  • An application that makes an outgoing call is the initial sole owner of that call. Other applications monitoring the line will be informed of the outgoing call at the time the first LINE_CALLSTATE message is received. Usually, this notification occurs when a dial tone is initially detected.
  • Ownership of an incoming call is assigned to one application only. This assignment avoids the situation in which, depending on timing, different applications may seize control at different times, causing unpredictable results.
  • An application that is currently an owner of a call can pass ("hand off") ownership to another application that has the call's line open. While handing off ownership of a call, the original owner application can specify the new media type of the call. When the handoff succeeds, the original application remains an owner of the call, and it can then choose to either deallocate its handle (if it is no longer interested in the call), change to being a monitor (using lineSetCallPrivilege), or remain an owner (although doing so is discouraged). The original application's privilege is not automatically changed by lineHandoff. For more information on the two types of call handoffs (directed and media-mode), see Directed Handoffs and Media Mode Handoffs.
  • If a target application for the handoff is found, and if it is already a co-owner of the call, it will see no effect caused by the handoff, although it will receive a LINE_CALLSTATE message. This message repeats the fact that it is an owner to alert it that another application has explicitly asked it to take control of the call. The application initiating the handoff is informed about the success of the handoff.
  • If there is no target application for the requested handoff and the call is active, an error is returned. No handoff takes place.
  • Handing off a call between applications never affects the state of the physical call as perceived by the switch or the service provider.
  • An application that does not have (but wants) ownership of a call may request ownership. The application can select calls based on a number of criteria, ranging from all calls on a particular line or address (a phone number assigned to the line, using lineGetNewCalls), to calls related to a specified call (using lineGetConfRelatedCalls). An application that calls lineGetNewCalls or lineGetConfRelatedCalls will always receive a monitor handle. If it wants to become an owner of a call it receives, it must then call lineSetCallPrivilege. If it determines that it is not interested in one or more of the calls to which it receives handles using lineGetNewCalls or lineGetConfRelatedCalls, it must call lineDeallocateCall for each such handle to release the internal resources maintained to track the call ownership.
  • Any application that asks for ownership receives it; any application that is offered ownership cannot refuse it. An application that becomes an owner through a handoff actually becomes a co-owner of the call. When the call is initially presented by the provider, the initial owner is the sole owner of the call.
  • The originally owning applications are informed about the existence of every new owner. Monitoring applications are informed as well.

Note Co-owned calls (calls simultaneously owned by more than one application), no protection is offered to prevent the applications from interfering with each other. For this reason, maintaining ownership after a handoff or after ownership is taken by another application is discouraged.

Because media streams are not managed by the Telephony API, call handoff does not handle the handoff of the call's media stream. Media-stream handoff must be carried out using commands from an appropriate media-control API or directly coordinated between the applications involved.


Handling Incoming Calls

When multiple applications are running simultaneously, an appropriate one must be found to become the initial owner of each incoming call. In general, incoming calls reach their destination, or target application, in these steps. First, the service provider learns of the new call and passes it to the TAPI dynamic-link library which gives the call to the appropriate application. Finally, applications conduct probing, if necessary, which can cause the call to be handed off between applications one or more times. These steps are described in the following topics. Sometimes applications perform further probing, a case which is also covered in the following topics.


Duties of the Service Provider

The service provider determines the media modes, beginning with an initial assessment based upon incoming data, settings, and equipment attributes.


Determining Initial Media Modes

When a service provider learns of the appearance of a call, its first task is to determine the call's media mode to the best of its ability. (It has received ringing voltage on a POTS line or, in the case of EPBX or ISDN, a protocol message indicating that a call is incoming.) It may be able to tell the single correct media mode or it may only be able to narrow down the possibilities to a certain few. These first media mode settings are called initial media modes, and the following are the considerations used for setting initial media mode bits:

  • Service provider setup The service provider has been configured to work with only a single media mode or certain media modes.
  • Hardware limitations Hardware limitations are usually reflected in the service provider's configuration, but the media modes could be further restricted by a particular card in use.
  • Call to lineOpen Possible media modes are limited by what applications have requested in their invocation of the lineOpen function. TAPI combines all of the media modes requested by applications and indicates the sum of them to the service provider in a call to TSPI_lineSetDefaultMediaDetection. For example, a telephony device and its service provider may be able to handle Group 3 fax calls, but if no application is running to handle such calls, the provider would know not to bother with probing for fax or reporting fax calls to TAPI. (The TAPI dynamic-link library does not automatically launch an application to handle a particular type of incoming call.)
  • Caller ID and Direct Inward Dialing With Direct Inward Dialing (DID) at the called address, the switch supplies the service provider with the digits that were dialed (the called address). The service provider can be configured to associate particular called addresses with particular media modes. Likewise, it could associate calls from particular numbers as being associated with particular media modes, although this is much less commonly used.
  • Distinctive ringing The ring pattern of the incoming call may match a predetermined pattern (of several possible at the called address) that is reserved for calls of a certain media mode. If, for example, the incoming call is using ring pattern 2, the service provider knows it to be a fax call (based on configuration information supplied by the user).
  • ISDN On an ISDN network, the provider may analyze the call's protocol frames to determine the media mode. If the call is indicated as a 3.1 kHz voice call, it is still possible that the actual media mode on the call is analog data modem, Group 3 fax, text telephone, or any of several other voiceband modulated signals, in addition to human voice; it is only with digital data signals that the media mode would necessarily be clearly defined—for example as Group 4 fax—at call setup time in ISDN.
  • Auto answer and probe Some providers give the user an option to let the service provider autoanswer the call and do some of the probing itself. In this process, TAPI gives the call the correct application with the correct media mode already identified.

These tools may be enough to make a final and accurate determination of the media mode. In any case, when the service provider passes the new call to TAPI, it sends a LINE_CALLSTATE message and includes in the message all that it knows about the call's media mode(s). The following topics give details on the possible cases.


Known Media Mode

When the service provider knows the media of the call unambiguously, one flag is set in dwMediaMode in LINECALLINFO. The media mode cannot be the single bit LINEMEDIAMODE_UNKNOWN, which is a different scenario. TAPI gives ownership of the call to the highest priority application that has opened a line for this media mode. It also gives call handles with monitor privileges to all other monitor applications on the line.


Unknown Media Mode

Even when the service provider does not know the exact media mode of the call, it might still know which media modes are possible. In this case, the service provider sets a combination of likely media mode bit flags, including LINEMEDIAMODE_UNKNOWN and passes the call to TAPI. The service provider sets these bits both in the dwMediaMode member of the LINECALLINFO record and in the dwParam3 parameter of the first LINE_CALLSTATE message it sends to TAPI.

The service provider considers only the media modes for which applications have opened the line with owner privileges (it becomes aware of these media modes through the TSPI_SetDefaultMediaDetection call) and which it is capable of handling. TAPI informs the provider about the union of all the lines that have been opened with a specified media mode. The provider can use this union to enable only the appropriate media mode detections for which applications are interested. If no applications have opened the line for ownership, the provider will not consider any media modes. Incoming calls are still delivered to TAPI, but no initial owner is possible. In this case, monitoring applications will still be informed of the call, and if none of them changes their privilege to owner and answers the call, the call will remain unanswered.


Duties of the TAPI Dynamic-Link Library

The TAPI dynamic-link library (DLL) does not perform probing; that is, it does not send signals on phone lines in order to determine a call's media mode. TAPI does try to deliver the call to an application that can do probing. The way in which TAPI gives calls to applications is determined by several factors, the most important of which are the media mode bits that have been set and the running applications that can (or cannot) handle calls of those media modes.

TAPI's behavior can be divided into two main scenarios: one media mode bit is set, and the UNKNOWN bit is set. These cases are described in the following topics.


Only One Media Mode Bit Is Set

If only one media mode bit (not the UNKNOWN bit) has been set in the dwMediaMode member of the LINECALLINFO data structure, TAPI distributes calls by following a consistent procedure based on the current state of the system and on information saved by the user in the registry. These are the steps it takes:

  • The TAPI DLL is notified by the service provider that a call is arriving.
  • The TAPI DLL uses the information in the HandoffPriorities subkey of the registry to know which applications are listed, possibly through a Preferences option in the application's user interface, as being interested in calls having the incoming call's media mode.
  • The first such application listed, reading left to right, is the highest priority application. If that application is currently running and has the arriving call's line open for that media mode, it is given ownership of the call. If it is not running or it does not have that line open, TAPI again uses the information in the registry to find an interested application in the correct state, and it gives the call to it.
  • If none of the applications listed in the registry are in the proper state, TAPI looks for other applications that are currently executing and have the line open for that media mode (though they are not listed in the registry). The relative priority among these unlisted applications is arbitrary and not necessarily associated with the sequence in which they were launched or opened the line.
  • Every application that has the line open for monitoring also receives a handle to a call, and any of them could step up, claim ownership (by calling lineSetCallPrivilege), and answer the call. However, this behavior could result in race conditions and unpredictable call handling, and is therefore discouraged.
  • If no application becomes an owner of the call, the call is eventually dropped. Calls can be dropped by TAPI only if no owner is found for the call and the call state is not idle or offering. The calling party can also drop the call. (On an ISDN network, this event becomes known when a "call-disconnect" frame is received.) If the call is not explicitly dropped, it can go idle after the expiration of a timeout based on the absence of ringing. (The service provider would need to assume that the call has been dropped by the calling party, and implement the timeout.) Because there were no applications that could take the call successfully, this situation usually means that the incoming call reached a wrong number.


The UNKNOWN Bit Is Set

If the LINEMEDIAMODE_UNKNOWN bit is on in dwParam3 of the first LINE_CALLSTATE message delivered by the service provider, the call is treated differently depending on whether an application prepared to accept calls of unknown media type has opened the line. For more information about these two possible cases (an unknown application is running, or is not), see An Unknown Application Is Running or No Unknown Application Is Running.


An Unknown Application Is Running

If at least one unknown application has opened the line, the TAPI dynamic-link library gives an ownership handle for the incoming call to the highest priority unknown application. It also passes monitoring handles to the other applications that have the line open for monitoring. The unknown application receives a LINE_CALLSTATE message with dwParam3 set to owner.

This unknown application can then try to perform media determination itself, or use the assistance of the other media applications, allowing them to perform probes for their media mode(s), if appropriate. The unknown application can pass the call to another media application using lineHandoff. The unknown application would examine dwMediaMode in LINECALLINFO to determine the possible remaining candidate media. In doing so, it uses the highest priority media to determine the initial handoff target. It calls lineHandoff, specifying the single highest priority destination media mode as the target.

The following is the default priority of media modes, listed in order from first tried to last tried when used during media-type handoffs.

Order | Media Mode
1 | LINEMEDIAMODE_INTERACTIVEVOICE
2 | LINEMEDIAMODE_DATAMODEM
3 | LINEMEDIAMODE_G3FAX
4 | LINEMEDIAMODE_TDD
5 | LINEMEDIAMODE_G4FAX
6 | LINEMEDIAMODE_DIGITALDATA
7 | LINEMEDIAMODE_TELETEX
8 | LINEMEDIAMODE_VIDEOTEX
9 | LINEMEDIAMODE_TELEX
10 | LINEMEDIAMODE_MIXED
11 | LINEMEDIAMODE_ADSI

Automated voice is a media mode that has no meaningful distinction with interactivevoice at this level, and is therefore not listed.

If the handoff fails, the unknown application should clear that media mode flag in the dwMediaMode member of LINECALLINFO. This action moves the probe for the call one step closer to a final determination of the media mode. If the handoff indicates TARGETSELF, it means that the unknown application is the highest priority application for the media mode for which it was trying to hand off the call, so it should go ahead and do the probing itself.

If the handoff indicates SUCCESS, it means that a different application is the highest priority application for the media mode for which the call was being handed off. The unknown application should deallocate the call handle or change to being a monitor while the new owner has control and proceeds with probing.

The receiving application controls the call. If the probe is successful, it should set the correct media mode bit. If the probe fails, the application should clear the failed media mode bit in LINECALLINFO and hand the call off to the next highest priority application. If no more media mode bits are set, the handoff fails, because no suitable owner application exists for the call.

Eventually, the media mode may be identified through monitoring or successful probing, though the UNKNOWN bit still may be set in dwMediaMode in the data structure LINECALLINFO. In this case, the application that has received the call cannot be sure that it is the highest priority application for the identified media mode. It is now the duty of that application to ensure that the call goes to the highest priority application. To do so, the application follows these steps:

  • It calls lineSetMediaMode, which writes into the dwMediaMode member of the call to turn off the UNKNOWN bit and specify the newly identified media mode bit.
  • It calls lineHandoff to return the call to TAPI. The TAPI dynamic-link library is not explicitly specified in this command, but rather a media-type handoff is performed, through which the TAPI library knows that it must look for other applications to find the highest priority application for that media mode.
  • If this application is itself the highest priority application for this media mode, it receives a LINEERR_TARGETSELF return value (for the lineHandoff function call). This error means "No, you already are the highest priority application for that media mode." The application never loses control of the call, and it continues handling the call normally. If the lineHandoff succeeds, then there was a higher priority application for the identified media mode, and the application that called lineHandoff should deallocate its handle or change to being a monitor while the highest-priority application handles the call.

As long as the UNKNOWN bit is still on, the receiving application still does not know that the highest-priority media mode is present on the call, so it still needs to probe for it. It only considers the media mode to be present if the UNKNOWN bit is off—only then can it use the call as a call of that media mode.


Using Media Priorities While Probing

Unknown applications should take care to use default priorities of media modes (see An Unknown Application Is Running) when probing for applications to take calls of unknown media modes. One reason to do this is to protect human callers from hearing unpleasant fax or modem signals. If, for example, both the INTERACTIVEVOICE and the G3FAX bits are set in LINEMEDIAMODE_, a human caller may still be on the other end of the line. The application should wait to start probing for a fax (with a fax tone) until it determines that the call is not a voice call. It does this by probing first for voice, which occurs automatically if following the order stated in the default media-mode list.

However, while probing for high-priority media modes, it is a good idea to turn media monitoring on. This feature, invoked by calling lineMonitorMedia, detects signals that indicate other media. For example, one application may be playing an outgoing "leave a message" voice message while the incoming call starts sending a fax "calling" tone and waits for a handshake. In order not to lose the fax call, the local application needs to be monitoring for this tone while playing the voice message. Determining the lower-priority media (the fax call) while actively probing for the higher-priority media (voice) is not only a safer method—it helps prevent the loss of a call—it is efficient because it can shorten the probing process.


No Unknown Application is Running

If no unknown application has the line open, the TAPI dynamic-link library itself assumes the role of a simplistic unknown application. The TAPI library first passes an owner handle for the call to the highest priority application that is registered for the highest-priority media mode for which a media mode flag is set in the dwMediaMode member of LINECALLINFO. If there is no such application, the media mode flag is cleared, and TAPI tries the highest priority application for the next highest-priority media mode. If there is such an application, it can try to make a determination for the highest priority media mode in dwMediaMode in LINECALLINFO.

If no application is found to become the initial owner of a call, the call remains in the offering state until a monitor application becomes an owner through lineSetCallPrivilege, or until the call is abandoned by the calling party and is transitioned (by the service provider) to the idle state, at which time all monitoring applications deallocate their handles to the call.


Duties of the Media Mode Application

The media mode application that receives a call as a handoff target first checks the bit flags of dwMediaMode in LINECALLINFO. If only a single media mode flag is set, the call is officially of that media mode, and the application can act accordingly.

If the UNKNOWN and other media mode flags are set, the media mode of the call is officially UNKNOWN, but is assumed to be one of the media modes for which a flag is set in LINECALLINFO. The application should now probe for the highest priority media mode.

If more than one bit is set in LINECALLINFO and the call has not been answered, the application must perform a lineAnswer to continue probing. If the call has already been answered, the application can continue probing without having to first answer the call.

If the probe succeeds (either for the highest-priority media mode or for another one), the application should set dwMediaMode in LINECALLINFO to the single media mode that was recognized. If the actual media mode is this expected media mode, the application can act accordingly. Otherwise—if it makes a determination of another media mode—it must first attempt to hand off the call in case it is not the highest priority application for the detected media mode.

If the probe fails, the application should clear the flag for that media mode in dwMediaMode in LINECALLINFO, and hand the call off to the unknown application. It should also deallocate its call handle or revert back to monitoring the call. At this point, the fate of the call is determined by the steps described in An Unknown Application Is Running, depending on whether or not an unknown application is active.

If the attempt to hand off the call to the UNKNOWN application fails, this means that no unknown application is running. It is then the responsibility of the application that currently owns the call to attempt to hand it off to the next-highest-priority media mode (while leaving the UNKNOWN bit turned on in dwMediaMode in LINECALLINFO). If that handoff fails, the application should turn off that media bit, and attempt the next higher-priority bit, until the handoff succeeds or all of the bits are off except for the UNKNOWN bit.

If none of the media modes were determined to be the actual one, only the UNKNOWN flag will remain set in dwMediaMode in LINECALLINFO at the time the media application attempts to hand the call off to UNKNOWN. The final lineHandoff invocation will fail if the application is the only remaining owner of the call. This failure informs the application that it should drop the call and then deallocate the call's handle. At this point, the call is abandoned.


Receiving Incoming Calls

Once the target application has been determined, it is given the call. The following topics discuss the target application as it accepts and answers calls.


Accepting and Answering Calls

On a POTS network, the only reason for an application to call lineAccept is to inform other applications that it has accepted responsibility to present the call to the user. Similarly, on an ISDN line, the effect of accepting a call is to make other applications aware that some application has accepted responsibility for handling the call.

On an ISDN network, accepting a call also informs the switch that the application will present the call to the user (by alerting the user for example, by ringing or by popping up a dialog box). If the LINEADDRCAPFLAGS_ACCEPTTOALERT bit is set, the application must perform a lineAccept on the call or the call will not ring. If the application fails to call lineAccept quickly enough (the timeout may be as short as three seconds on some ISDN networks), the network will assume that the station is powered off or disconnected and act accordingly, such as by deflecting the call (if Forward on No Answer is activated) or sending a disconnect message to the calling station.

Accepting a call is not the same as answering a call. Answering calls, in POTS, simply means to go offhook. On an ISDN line, it means to tell the switch to place the call in a connected state. Before answering, there is no physical connection for the call between the switch and the destination, though the call is connected from the caller to the switch.

Sometimes a call has already been answered when a new application takes control of it. This can occur, for example, when one application discovers that it is not the highest priority application for a call of a given media mode, and it hands the call off. If the first application has already answered the call, the receiving application takes control of an answered call. It should treat the call normally—that is, as if it had answered the call itself. Another example is when a user instructs an application to operate on an existing call. In this case, the application seizes the call. Again, it should treat the call as if it had answered it.


Waiting a Minimum Number of Rings

The lineGetNumRings function can be used by any application to determine the number of times an incoming call on the given address should ring before the call is to be answered. Waiting a certain number of rings allows callers to be spared the charge of a call connection if it seems that the call will not be answered by the desired party (usually a person). This feature is sometimes called toll-saver support. Applications can use the lineGetNumRings and lineSetNumRings functions in combination to provide a mechanism to support toll-saver features for multiple independent applications.

Any application that receives a handle for a call in the offering state and a LINE_LINEDEVSTATE ringing message should wait a number of rings equal to the number returned by lineGetNumRings before answering the call in order to honor the toll-saver settings across all applications. The lineGetNumRings function returns the minimum number of rings any application has specified with the lineSetNumRings function. Because this number may vary dynamically, an application should call lineGetNumRings each time it has the option to answer a call—that is, when it is the owner of a call still in the offering state. A separate LINE_LINEDEVSTATE ringing message is sent to the application for each ring cycle.

If the service provider is set to auto-answer calls, it answers after a certain number of rings. Service providers do not have access to the minimum-ring information established by lineSetNumRings, and therefore will make their own determination of when to automatically answer an incoming call. When a call has been so answered by a service provider, it will be initially delivered to the owning application already in the connected state, so the application will not need to be concerned with counting rings or with answering the call.


Taking Ownership of a Call

In general, when one application learns that another application wants ownership of a call, it simply relinquishes ownership of the call to that other application. Although there can be many co-owners of a call, it should be a transitory state for there to be multiple owners.

In one specific case, it is valid for an application to actively take ownership of a call owned by another application. This is when the application is instructed to do so by the user—perhaps through a user interface. For example, a fax application may be instructed by a user to break into that same user's existing voice call and use the call to send a fax. In this case, the fax application takes ownership from the previous owner, the application that was controlling the voice call.

An application can forcibly become owner of a call by taking the following steps:

  • Obtain a handle to the call with monitor privilege. If the desired call is one for which the application does not yet have a handle, it should request a handle with lineGetNewCalls. If the application is already a co-owner of the call and wants to become sole owner, it should start by calling lineSetCallPrivilege with the dwCallPrivilege parameter set to LINECALLPRIVILEGE_MONITOR. This action, which relinquishes ownership of the call (temporarily, in this case), is seen by other applications as the departure of an owner.
  • Call lineSetCallPrivilege with the dwCallPrivilege parameter set to LINECALLPRIVILEGE_OWNER for the call. Other applications see a new owner coming on line by receiving a LINE_CALLINFO message stating that the number of owners has increased and the number of monitors has changed; the bit LINECALLINFOSTATE_NUMOWNERINCR is on. These applications should yield the call to the new owner but there is no guarantee that they will do so. If the other existing owners do relinquish ownership, the new owner can proceed with what it intended to do on the call.

Note There is no way to shield a call from another application's attempt to become an owner of it, nor is there any reason to do so. Once an application is informed that another application has become an owner, it should draw its activities on the call to an orderly close, and then relinquish ownership, because such changes in ownership are almost always done at the explicit direction of the user.


Relinquishing a Call

An application can relinquish ownership of a call by invoking lineSetCallPrivilege to change to a monitor application, or simply by using lineDeallocateCall to indicate that it has no further interest in the call. If the application is the sole owner of the call and cannot hand off ownership to another application, TAPI will not permit it to change to being a monitor or to deallocate its call handle—in this situation, the application has no choice but to drop the call.


Control of the Media Stream

An application that has just obtained a call may not immediately receive control of the media stream, and may need to wait until the previous owner application relinquishes it. Though this may take time, any application with control of the media stream should transfer control when it sees that a new owner has come on line (the number of owners has increased).

The procedures for transferring control of an active media stream differ for every media-control API. The API may allow only one application to have a media-stream device (such as a COM port used for data transfer) open. In this case, it is important that the current owner relinquish control of a media stream device before handing off the call. But with some other types of media such as WAV audio, several applications (and several devices) can have the media stream open at the same time. This makes it unnecessary to close the media stream before the handoff, and perhaps not at all.


Call Handoffs

After an application has acquired ownership of the call, ownership can be transferred to another application. Why would this be necessary? Normally, to allow the call's media mode to be changed. In this case, the highest priority application for the new media mode should take and handle the call. Media mode changing usually occurs because of one of the following causes.

User command Through a user interface or through window messages, the application learns that the local user wants to change media mode. For example, the user has told the new target application (which is not yet an owner) to obtain an existing voice call for transmitting data. The target application must now take control of the call. In this case, the current owner notices the number of owners increase, and then relinquishes its control of the call. Alternatively, the user could instruct the current owner of the call to hand it off to an application that can handle the new media mode.

Media mode change The service provider can detect a media mode change with lineMonitorMedia. As an example of this, the local application is playing a recorded voice message to the caller. During this message, the caller spontaneously decides to transmit a fax calling tone, and the local application can respond accordingly by changing the media mode to fax and, if necessary, handing the call off to a fax application. Another way this can work is for a monitoring application to enable media mode monitoring, and, when the media mode in which it is interested is detected on a call, it can request ownership of the call. This mechanism makes it unnecessary for every application to monitor every call for every media mode.

Remote party command The remote party can interactively indicate a change in media modes during an existing call. For example, the local application is using lineMonitorDigits to monitor DTMF input by the remote caller. Through this monitoring, the caller indicates, for example, that a fax is about to be sent. Other ways the caller can control local applications are with commands received on other data connections and through ISDN user-user information messages.

A call handoff will have one of these outcomes:

  • The call is given to another application (SUCCESS).
  • The handing-off application is itself the target (TARGETSELF).
  • The handoff fails (TARGETNOTFOUND).

If the application that is receiving the handed-off call already has a call handle to the call, this old call handle is used. Otherwise a new call handle is created. In either case, the application ends up with owner privileges to the call. Whenever the handing-off application is not the same as the target application, the target is informed about the handoff in a LINE_CALLSTATE message with dwParam3 set to LINECALLPRIVILEGE_OWNER, as if it were receiving a new call.

Note The dwParam3 parameter of the LINE_CALLSTATE message is set to owner only if the LINE_CALLSTATE message is being sent to an application that is the initial owner of a new call, is the target of a handoff, or was previously a monitor or an owner of the call. The dwParam3 parameter can be set to monitor only if the LINE_CALLSTATE message is sent to the application when it is presented a new call for monitoring. In all other cases (such as when the application already has a handle to the call, and its ownership state is not being changed), dwParam3 is set to zero.

If the current owner application is told to change modes, it does so by handing off the call to an application used for the target media mode. The two types of call handoffs are described in Directed Handoffs and Media Mode Handoffs.


Directed Handoffs

A directed handoff takes place when the target application is known by name to the original application. This situation would occur, for example, among a set of applications written by the same vendor. Control of directed handoffs can usually be configured by the user. With such a handoff, the call is given to the specified application if it has opened the line on which the call exists. The media mode specified at the time the application opened the line is ignored. One common example is a voice call followed by fax transmission in the same call. Directed handoff would most often be used by applications from the same developer that are linked in other ways as well.

Directed handoff may also be used in future versions as part of the process of arbitrating multiple applications waiting for incoming calls of the same media mode, with the selection of the application to handle the call being based on data-link or higher level protocol detection rather than media mode. An example of its use would be an incoming data modem line with applications such as remote takeover, bulletin board, remote network access, and remote e-mail access all waiting for calls simultaneously.


Media Mode Handoffs

A media mode handoff takes place when there is a new, targeted media mode, usually when the owning application determines that the media mode needed for the call is not present or is about to change. The process for a media-dependent handoff can be a probing process if the UNKNOWN bit is on, and is virtually the same as for the initial assignment of a call to an application. The difference is the fact that lineHandoff can have only one media-mode bit set.

Because only a single media mode bit can be specified, the call is given to the highest priority application for that media mode. However, it is possible that more than one media mode is to be considered for the handoff. In this case, the handing-off application should specify the highest priority of the possible media modes as a parameter for lineHandoff. If an application specifies the UNKNOWN bit when performing a media-mode handoff and the handoff fails, this means that no unknown application is currently running. The application that is handing off should then try to hand the call off to the highest priority application registered for the next higher media mode.

The receiving application is now responsible for the call. It now probes for the call's actual media mode. If the call's media mode matches that handled by the application, it must ensure that it is the highest-priority application registered for that media mode. If so, it keeps the call and processes it normally. If not, it hands the call off to another application registered for that media mode.

If, however, the probe for that media mode fails, the application probes again, attempting the remaining media-mode possibilities. It determines these by examining the dwMediaMode member in the LINECALLINFO structure. But first, using the lineSetMediaMode function, the owning application turns off the bit for the current (disproved) media mode in the dwMediaMode member.

This process of probing and handing off continues, and the remaining media modes are eliminated one by one. Along the way, one of the applications may see that the media mode it handles is on the call, and the handoff is successful. The application should now perform a final lineSetMediaMode to set the correct media mode and clear all other media-mode bits. This informs other interested applications of the correct media mode. These other applications receive a LINE_CALLINFO message stating that the call's media mode has changed. To determine the correct media mode, they invoke lineGetCallInfo and examine the dwMediaMode member in the LINECALLINFO structure.

It is the responsibility of the owning application to cycle through media modes to find the highest-priority application. TAPI does this cycling only on the initial incoming call to find the first owner. It does not do it when lineHandoff is called.

To sum up the media-mode handoff process, TAPI does not check for other media bits during lineHandoff. TAPI only attempts to hand off to the single media mode indicated in the parameter to lineHandoff. It is up to the application to turn off the bit corresponding to the media mode that failed to hand off, and to try other media modes until the handoff succeeds or all the possible media modes are exhausted. If it gets to a point where all of the bits are off except for UNKNOWN, it must abandon the call by calling lineDrop and then deallocating the handle.


Logging Calls

Logging a call simply means actively recording the actions and states of a monitored call into a file on a disk. (An application that owns a call is also a monitor of that call.) Though limited call logging is performed by the call manager provided with Win32 Telephony, any application can be programmed to log a call that it is monitoring.

TAPI facilitates logging by allowing applications to monitor calls and by collecting information from other applications that are controlling calls. TAPI writes the information it collects into the LINECALLINFO structure, which can then be read by applications.


Sources of Log Information

Information useful to call logging (which is saved by TAPI) originates in the following sources, and is placed in the LINECALLINFO data structure.

  • In an application's call of the initialization function, lineInitializeEx, it provides information such as the application's name. An application should ensure that the information it provides with the initialization command is accurate so that its activities are reflected correctly in the call log.
  • The LINECALLPARAMS data structure, used in the lineMakeCall function, stores information such as the name of the called party, the originating address, and the destination address. This structure is passed to TAPI by any application that originates a call.
  • The service provider supplies many items that can be logged such as the caller's ID.
  • The LINE_CALLSTATE messages that pertain to a given call are an important source of logging information, indicating whether the call successfully connected or was abandoned because of a busy signal, no answer, network congestion, or other causes.

The start time, end time, and duration of a call are not recorded by TAPI. A logging application that wants to log this information must record the time by checking the system clock when certain LINE_CALLSTATE messages (such as CONNECTED, DISCONNECTED, and IDLE) are received, and then derive the related time log information.


Using the LINECALLINFO Data Structure

The LINECALLINFO structure stores a large amount of information about a call, and is thus an important source of data. Generally, a logging application reads from LINECALLINFO and writes this information into its log file.

A separate LINECALLINFO structure exists for every incoming and outgoing call. Information in this structure is obtained by an application with lineGetCallInfo. An application typically reads the information from LINECALLINFO at the following times:

  • When the application first receives a handle for a call in the LINE_CALLSTATE message.
  • Each time the application receives notification in a LINE_CALLINFO message that LINECALLINFO has changed. Whenever any part of the structure changes, a LINE_CALLINFO message is sent to the application indicating which information item has changed.

Both the LINE_CALLSTATE message and the LINE_CALLINFO message also supply the call's handle as a parameter.

Much of the information held in LINECALLINFO remains fixed for the duration of the call. Information about a call that changes dynamically, such as call progress status, is available in the LINECALLSTATUS structure, which is returned with the lineGetCallStatus function. Other information needed by logging applications that is not stored in LINECALLINFO is call start time, call stop time, and the call's duration, which it determines by checking the system time when the corresponding LINE_CALLSTATE messages are received.

LINECALLINFO stays intact after the call is disconnected, so the logging application can later read it in order to write additional information into the log. LINECALLINFO remains available only until the last application that had a handle for the call (owner and monitor handles) deallocates its handle.


Deallocating a Call

If an application is finished with a call and another application wants the call, the call can be handed off. But if no other applications want to take ownership, there is nothing to do but deallocate the call's handle. This is done with lineDeallocateCall. A call handle is no longer valid after it has been deallocated.

In contrast, dropping (disconnecting) a call puts the call in the idle state, which means that the local end of the connection is on hook. If the other end of the connection drops the call, the call transitions to the disconnected state, not the idle state. Typically, once an application receives a call-state message indicating the disconnected state, it immediately drops the call, causing it to become idle. Although the call is in the idle state, any handles to it held by applications remain valid until they are deallocated. If the call was never answered (the local end never went off hook), it may revert to the idle state without being dropped.

An application cannot deallocate a call if it is the sole owner and the call's state is not idle. This is because TAPI tries to ensure that there is always at least one owner for every active call. If the application is the sole owner and the call is not idle, the error message LINEERR_INVALCALLSTATE is returned. If an application needs to circumvent this restriction, it can do so by dropping the call first (with lineDrop) and then deallocating its handle. This prevents an application from deallocating its handle which would result in a call disconnect. By making the application do an explicit drop, it can inform the user (in a dialog box) that the call is about to be disconnected.

If releasing the ownership handle results in the call's having no more handles, TAPI calls the service provider function TSPI_lineCloseCall. When this function is invoked on a call that is not yet idle, it is up to the service provider to drop the call.

Note An application that has monitor privileges for a call can always deallocate its handle for the call. Deallocating a call does not affect the call state of the physical call, but it does release the internal resources (memory) related to the call.

An application should deallocate the handle to a call it owns in these two cases:

  • Idle call state If an application receives a LINE_CALLSTATE message indicating that the call has transitioned to the idle state, and has already gathered all the information it needs about the call, it should deallocate the call handle immediately.
  • Handoff The application has handed off the call (or has otherwise relinquished call ownership to another application) or has set its call privilege to monitor, and has no interest in monitoring or logging the call.

Failure to deallocate call handles in a timely way can result in system failure and lost calls due to unnecessary consumption of memory and other resources.


Closing Lines

An application should close a line it has open in the following cases:

  • Before exiting An application should always close all lines it has open before it becomes inactive.
  • For non-TAPI applications TAPI applications should cooperate with non-TAPI applications that use media stream devices such as COM ports. If your TAPI device is a serial device accessed through a COM port (such as a modem) and the line is open, the service provider needs to have the COM port open. But with the COM port open, non-TAPI applications and console applications are prevented from accessing the COM port. Therefore, a TAPI application should open the line (and keep it open) only if it is waiting for incoming calls or it is actively engaged in placing an outgoing call.
  • Non-telephony communications applications may need to share resources with telephony applications.

The data structure LINEDEVCAPS contains a capabilities bit (LINEDEVCAPFLAGS_CLOSEDROP) that tells whether closing a line while a call is still active causes calls on the line to be dropped. If TRUE, the service provider drops (clears) all active calls on the line when the last application having that line open closes it using the lineClose function. If the bit is set to FALSE, the service provider does not drop active calls on the line; instead, it leaves these calls active and under the control of an external device or devices, such as phones.

Therefore, an application can examine LINEDEVCAPS to detect in advance whether closing a line will cause this active call to be dropped. The application should warn all appropriate users that the call is about to be dropped, perhaps by displaying an OK/Cancel dialog box that lets the user keep the line open.

For example, if a desktop computer and a phone set are both connected directly to an analog line (in a party-line configuration), the service provider should set the flag to FALSE, as the offhook phone would automatically keep the call active even after the computer is shut down.

As another example, a user is speaking on the phone on a call owned by an active application. The user decides to leave the office for the day and shuts down the system. The operating system in turn shuts down the active telephony application, which attempts to close the lines it has open. Whether the call is automatically disconnected depends on whether the LINEDEVCAPFLAGS_CLOSEDROP bit in LINEDEVCAPS is set or not and whether the phone is offhook.

If other applications are monitoring the call, the service provider will not even be informed that one application has closed the line. It is only when the last application that has a handle to the call closes the line that the service provider is informed (with TSPI_lineClose). At that point, it is up to the service provider to handle any remaining calls. If the service provider is required to drop the calls, it should do so but it should first warn applications about this requirement with the LINEDEVCAPFLAGS_CLOSEDROP flag.

Closing an application should ideally perform the following cleanup tasks:

  • Dispose of all calls.
  • Close all open lines and phones.
  • Shut down the usage of the Telephony API.

Failure to do so may leave calls in indeterminate states.


Learning About Existing Calls at Application Startup

Applications can become aware of existing calls on the line at the time of application startup with lineGetNewCalls. This function gives the application handles using monitor privilege to all the calls on the line or address for which it did not already have handles.

An example of the usefulness of this mechanism is when a user starts a fax application during a voice call, having decided to send a fax. The new fax application needs to discover the existing call (using lineGetNewCalls) to request ownership of the call in order to send the fax.


Media Mode Updating

A call's media mode as stated in dwMediaMode in LINECALLINFO and a media mode message (LINE_MONITORMEDIA) sent from the service provider to the application can and often will differ. An application could use lineMonitorMedia to enable monitoring for particular media modes, and use any resulting LINE_MONITORMEDIA messages as guidance in determining what the calling party might be probing for or what the unknown application should probe for first. LINE_MONITORMEDIA messages report events on the line (such as probes being received from the remote station) and not "hard" decisions about media modes. When an application determines that a call involves a particular media mode, it calls lineSetMediaMode to update dwMediaMode in LINECALLINFO and inform other applications of this update.


Communication Between Applications

Applications can communicate with each other by writing to and reading from a field in a specified call's information record, the LINECALLINFO data structure. With lineSetAppSpecific, any owner application can write to the application-specific member called dwAppSpecific. It is uninterpreted by the Telephony API or any of its service providers. This member's usage is entirely controlled by applications.

The member can be read from the LINECALLINFO record returned by lineGetCallInfo. However, lineSetAppSpecific must be used to set the member so that changes become visible to other applications. When this member is changed, all other applications with call handles are sent a LINE_CALLINFO message with an indication that the dwAppSpecific member has changed.


Special Cases in TAPI

Occasionally, the TAPI call encounters special circumstances:

  • A call with no owner
  • A call answered elsewhere on the line
  • A call that is auto-answered by the service provider

The following topics describe situations that could occur in multiple-application environments.


A Call Without an Owner

What happens to an incoming call if no applications have the line open with owner privilege? First, TAPI informs all monitoring applications on the line about the call. If no monitoring application switches to owner privilege to answer the call, the service provider eventually drops the call.

The following steps describe what normally happens if a line has only monitoring applications, a call comes in, and no applications answer the call. Assume that the service provider is not configured to answer new calls by itself.

  • The service provider passes the call handle to TAPI.
  • TAPI passes monitor handles to the monitoring applications.
  • TAPI determines that the call is in the offering (not connected) state and lets the call "sit."
  • The remote party eventually hangs up, and the call reverts to the idle call state because it was never connected.
  • The monitors are notified that the call is idle and deallocate their handles if they have not already done so.
  • The last deallocation causes a TSPI_lineCloseCall.

Although the call in this example was never answered, its appearance and disappearance may have been significant to the applications monitoring the line. On a network that offers caller ID, a user may want to screen incoming calls, recording who has called without necessarily answering every call. Monitoring applications can help accomplish this without ever needing to answer a call.


The Call is Answered Elsewhere

This scenario is similar to a call without an owner, but the user answers the phone elsewhere on the line, and this answer is detected by the provider through the hardware. The call is reported as being in the connected state, though it is not connected to any application on the local computer. The call eventually goes idle, at which point each application (monitoring as well as all owner applications) must deallocate its handle.

The following steps describe what occurs in a scenario in which a line has only monitoring applications, the service provider is configured to not answer new calls by itself, and a call comes in:

  • The service provider passes the call handle to TAPI.
  • TAPI passes monitor handles to the monitoring applications.
  • TAPI determines that the call is in the offering (not connected) state and lets the call "sit."
  • The user picks up a ringing downline phone, and the call becomes connected.
  • All monitoring applications are sent a corresponding LINE_CALLSTATE message.
  • The user eventually hangs up the downline phone, and the call reverts to the idle state.
  • The monitor applications are notified the call is idle and deallocate their handles, if they have not already done so.
  • The last deallocation causes a TSPI_lineCloseCall.


Auto-Answer by the Service Provider

In this scenario, the provider is set up to auto-answer a new call. The provider answers it and determines the call's media mode. It then informs TAPI of the call. Because no applications decide to take ownership, TAPI cannot pass the call to any application.

The following steps describe what occurs in a scenario in which a line has only monitoring applications, the service provider is configured to auto-answer all new calls, and a call comes in.

  • The service provider passes the call handle to TAPI.
  • TAPI passes monitor handles to the monitor applications (the call is in the connected state).
  • TAPI realizes that the call is connected, but there are, so far, no potential owners.
  • TAPI must call TSPI_lineDrop to cause the call to revert to idle.
  • The monitoring applications are notified that the call is idle and deallocate their handles if they have not already done so.
  • The last deallocation causes a TSPI_lineCloseCall.

This example illustrates an important point for writers of monitoring applications. It is not a good idea to wait to monitor for incoming calls you later want to own. It is better to open the line as an owner, because there might not be enough time to change your privilege from monitor to owner before TAPI drops the call.


Call States and Events

A connection is not fully established until both parties are communicating. To reach that point, the establishment of the call goes through several stages, as does the clearing (termination) of the call. A call's events cause it to transition through call states as it comes into existence, is used to exchange information, and terminates. These call-state transitions result from both solicited and unsolicited events. A solicited event is one caused by the application controlling the call (as when it invokes TAPI operations), while unsolicited events are caused by the switch, the telephone network, the user pressing buttons on the local phone, or the actions of the remote party. Some operations on line devices, addresses, and calls may first require that the line, address, or call upon which they operate be in certain specific states.

Different call states indicate that connections exist to different parts of the switch. For example, a dial tone is a particular state of a switch that means the computer is ready to receive digits.

Whenever a call changes state, TAPI reports the new state to the application in a message. This programming model, therefore, is one in which the application reacts to the events reported to it, as opposed to a rigid call-state model. In other words, call-state notification tells the application what the call's new state is, instead of reporting the occurrence of specific events and assuming that the application will be able to deduce the transitions between two states.


Call State Definitions

Some of the call states and events defined by TAPI are exclusive to incoming or outgoing call processing, while others occur in both cases. Several of these call states provide additional information that can be used by the application. For example, the busy state signifies that a call cannot be completed because a resource between the originator and the destination is unavailable, as when an intermediate switch has reached its capacity and cannot handle an additional call. Information supplied with the busy state includes station busy or trunk busy. Station busy means that the destination's station is busy (the phone is offhook), while trunk busy means that a circuit in the switch or network is busy. The call states defined by TAPI are listed below.

Call State | Description
idle | This corresponds to the "null" state: No activity exists on the call, which means that no call is currently active.
offering (incoming) | When the switch informs the computer of the arrival of a new incoming call, that call is in the offering state. The offering state is not the same as causing a phone or computer to ring. When a call is offered, the computer is not necessarily instructed to alert the user.
 | Example: An incoming call on a shared call appearance is offered to all stations that share the appearance, but typically only the station that has the appearance as its primary address is instructed to ring. If that station does not answer after some amount of time, the bridging stations may be instructed to ring as well.
accepted (incoming) | An application has taken responsibility for an incoming call. In ISDN, the accepted state is entered when the called-party equipment sends a message to the switch indicating that it is willing to present the call to the called person; this has the side effect of alerting the users at both sides of the call: the caller's and the called party's. An incoming call can always be immediately answered without first being separately accepted.
dial tone (outgoing) | Indicates that the switch is ready to receive a dialable number. In most telephony environments, this state is entered when audible dial tone is detected by the line device. Additional information includes:
—normal dial tone | The "normal" or everyday dial tone, usually a continuous tone.
—special dial tone | A special dial tone is often used to signal certain conditions such as message-waiting. This is usually an interrupted dial tone.
dialing (outgoing) | The originator is dialing digits on the call. The dialed digits are collected by the switch.
proceeding (outgoing) | The call is proceeding through the network. This occurs after dialing is complete and before the call reaches the dialed party, as indicated by ringback, busy, or answer.
special info (outgoing) | The call is receiving a special information signal, which precedes a prerecorded announcement indicating why a call cannot be completed. Such announcements can be of these types:
—no circuit | A no-circuit or emergency announcement.
—customer irregularity | An announcement meaning that the dialed number is not correct.
—reorder | A reorder or equipment-irregularity announcement.
busy (outgoing) | The call is receiving a busy signal. Busy indicates that some resource is not available and the call cannot be normally completed at this time. Additional information consists of:
—station busy | The station at the other end is offhook.
—trunk busy | The network is congested. This usually produces a "fast busy" signal.
ringback (outgoing) | The station to be called has been reached, and the destination's switch is generating a ring tone back to the originator. A ringback means that the destination address is being alerted to the call.
connected (incoming and outgoing) | Information is being exchanged over the call.
on hold (incoming and outgoing) | The call is currently held by the switch. This frees the physical line, which allows another call to use the line.
conferenced (incoming and outgoing) | The call is a member of a conference call and is logically in the connected state (to the conference bridge). A call in the conferenced state refers to a conference call (in the connected, onHold, ... state).
on hold pending conference (incoming and outgoing) | The conference call is currently on hold and waiting for the user to add another party.
on hold pending transfer (incoming and outgoing) | The call is on hold in preparation of being transferred.
disconnected (incoming and outgoing) | The call has been disconnected by the remote party.
unknown (incoming and outgoing) | The call exists, but its state is currently unknown. This may be the result of poor call progress detection by the service provider. A call state message with the call state set to unknown may also be generated to inform the TAPI DLL about a new call at a time that the actual call state of the call is not exactly known.

Although under normal circumstances an outgoing call is likely to transition to connected through a number of intermediate states (dial tone, dialing, proceeding, ringback), other paths are often possible. For example, the ringback state may be skipped, as when a hot phone (or other nondialed phone) transitions directly to connected.

An application should always process call-state event notifications. Call-state transitions valid for one switch or configuration may be invalid for another. For example, consider a line from the switch that (using a simple Y-connector) physically terminates both at the computer and at a separate phone set, creating a party line configuration between the computer and the phone set. The computer termination and, therefore, the application using TAPI, may not know of the activities on the line handled by the phone set. That is, the line may be in use without the service provider being aware of it. An application that wants to make an outgoing call will succeed in allocating a call appearance from the API, but this results in sharing the active call on the line. In this case, blindly sending a DTMF dial string without first checking for a dial tone may not result in intended (or polite) behavior.


Obtaining Call State Information

Using the lineGetCallStatus function, an application can receive complete call status information for the specified call as a data structure of type LINECALLSTATUS. The lineGetCallInfo function returns mostly constant information about a call as a data structure of the type LINECALLINFO. The message LINE_CALLSTATE is sent unsolicited to an application to notify it about changes in a call's state.

The call-information data structure maintained for each call contains an application-specific member that applications can read from and write to. This member is not interpreted by TAPI. Applications can use it to tag calls in application-specific ways. Writing to this member so that the change is visible to other applications can be done with the lineSetAppSpecific function.


Supplementary Line Functions

In Win32 Telephony, supplementary functions are functions whose form and functionality have been defined by the API description, but which are not required in Basic Telephony. Developers of telephony applications and service providers may choose to implement these functions to suit the design of their custom products. That is, in contrast to Basic Telephony functions, Supplementary Telephony functions are optional.

This section describes the Supplementary functions used with TAPI-defined line devices. For convenience, they are grouped into general functional categories.


Bearer Mode and Rate

The notion of bearer mode corresponds to the quality of service requested from the network for establishing a call. It is important to keep the concept of bearer mode separate from that of media mode. The media mode of a call describes the type of information that is exchanged over a specific call of a given bearer mode. As an example, the analog telephone network (PSTN) provides only 3.1 kHz voice-grade quality of service—this is its bearer mode. However, a call with this bearer mode can support a variety of different media modes such as voice, fax, or data modem. In other words, media modes require certain bearer modes. TAPI manages the bearer modes only by passing the bearer mode parameters on to the network. Media modes are fully managed through the appropriate media stream APIs, although some limited support is provided in TAPI.

The bearer mode of a call is specified when the call is set up, or is provided when the call is offered. With line devices able to represent channel pools, it is possible for a service provider to allow calls to be established with wider bandwidth. The rate (or bandwidth) of a call is specified separately from the bearer mode, allowing an application to request arbitrary data rates.

The bearer modes defined in TAPI are:

  • Voice, which is regular 3.1 kHz analog voice service; bit integrity is not assured.
  • Speech, which is G.711 speech transmission on the call.
  • Multiuse, as defined by ISDN.
  • Data, which is unrestricted data transfer; the data rate is specified separately.
  • Alternate speech and data, which is the alternate transfer of speech and unrestricted data on a call (ISDN).
  • Non-call-associated signaling, which provides a clear signaling path from the application to the service provider.

Although support for changing a call's bearer mode or bandwidth is limited in networks today, TAPI provides an operation to request a change in the bearer mode or the data-rate parameters of an existing call. This function is lineSetCallParams.


Call Monitoring

Call monitoring includes media, digit, and tone monitoring, as described in the following topics.


Media Monitoring

When a call is in the connected state, information can be transported over the call. A call's media mode provides an indication of the type of information (for example, its datatype, or higher-level protocol) of this media stream. TAPI allows applications to be provided with a notification about changes in a call's media mode. The notification provides an indication of the call's new media mode. The service provider decides how it wants to make this determination. For example, the service provider could use signal processing of the media stream to determine the media mode, or it could rely on distinctive ringing patterns assigned to different media streams, or on information elements passed in an out-of-band signaling protocol. Independent of how the media mode determination is achieved, the application is simply informed about media mode changes on an existing call.

The media modes defined by TAPI include:

  • Unknown The media mode of the call is not currently known—the call is unclassified.
  • Interactive voice Voice energy was detected on the call, and the call is handled as an interactive voice call with a person at the application's end.
  • Automated voice Voice energy was detected on the call, and the call is handled as a voice call but with no person at the application's end, such as with an answering machine application.
  • Data modem A modem session on the call. Current modem protocols require the called station to initiate the handshake. For an incoming data modem call, the application can typically make no positive detection. How the service provider makes this determination is its choice. For example, a period of silence just after answering an incoming call can be used as a heuristic to decide that this might be a data modem call.
  • G3 fax A group 3 fax session on the call.
  • G4 fax A group 4 fax session on the call.
  • TDD The call's media stream uses the Telephony Devices for the Deaf protocol.
  • Digital data A digital data stream of unspecified format.
  • Teletex, Videotex, Telex, Mixed These correspond to the telematic services of the same names.
  • ADSI An Analog Display Services Interface session on the call. ADSI enhances voice calls with alphanumeric information downloaded to the phone and the use of soft buttons on the phone.

An application can enable or disable media monitoring on a specified call with lineMonitorMedia. The application specifies which media modes it is interested in monitoring, and when media monitoring is enabled, the detection of a media mode change causes the application to be notified with the LINE_MONITORMEDIA message. This message provides the call handle on which the media mode change was detected as well as the new media mode.

There is a distinction between the media mode of a call as reported by lineGetCallInfo and the media mode event reports by LINE_MONITORMEDIA messages. A call's media mode is determined exclusively by owner applications of the call and is not automatically changed by media monitoring events. The one exception is the initial media mode determination that can be performed by the TAPI dynamic-link library to select the first owner of a call. One could argue that in this case, the library is the owner of the call.

Default media mode monitoring is performed for the media modes for which the line device has been opened. This allows an incoming call's media mode to be determined before the call is handed to an application based on what the application demands. The scope of the media monitoring of a call is bound by the lifetime of the call. Media monitoring on a call ends as soon the call disconnects or goes idle.

An application can obtain device identifiers for various device classes associated with an opened line by calling lineGetID. This function takes a line handle, address, or call handle and a device class description. It returns the device identifier for the device of the given device class that is associated with the open line device, address, or call. If the device class is "tapi/line," then the device identifier of the line device is returned. If the device class is "mci/wave," then the device identifier of an mci waveaudio device is returned (if supported), which allows activities such as the recording or playback of audio over the call on the line.

The application can use the returned device identifier with the corresponding media API to query the device's capabilities and subsequently open the media device. For example, if your application needs to use the line as a waveform device, it must first call waveInGetDevCaps and/or waveOutGetDevCaps to determine the waveform capabilities of the device. The typical waveform data format supported by telephony in North America is 8-bit m-law at 8000 samples per second, although the wave device driver can convert this sample rate and companding to other more common multimedia audio formats.

To subsequently open a line device for audio playback using the waveform API, an application calls waveOutOpen. The implementation of waveOutOpen is device specific, and there are a variety of options for implementing this function.


Digit Monitoring

Digit monitoring monitors the call for digits. TAPI allows digits to be signaled according to two methods (digit modes):

  • Pulse Digits are signaled as pulse or rotary sequences. For detection, these pulses manifest themselves as nothing more than sequences of audible clicks. Valid pulse digits are '0' through '9'.
  • DTMF Digits are signaled as DTMF (Dual Tone Multiple Frequency) tones. Valid DTMF digits are '0' through '9', 'A'. 'B', 'C', 'D', '*', and '#'. Both the beginning and the down edge of DTMF digits can be monitored.

An application can enable or disable digit monitoring on a specified call with lineMonitorDigits. When digit monitoring is enabled, detected digits cause the application to be notified with the LINE_MONITORDIGITS message. This message provides the call handle on which the digit was detected as well as the digit value and the digit mode. The scope of digit monitoring is bound by the lifetime of the call. Digit monitoring on a call ends as soon as the call disconnects or goes idle.


Tone Monitoring

Tone monitoring monitors the media stream of a call for specified tones. A tone is described by its component frequencies and cadence. An implementation of the API may allow several different tones to be monitored simultaneously. An application can tag each tone to be able to distinguish the different tones for which it requests detection.

An application can enable or disable tone monitoring on a specified call with lineMonitorTones. With this function, the application indicates which tones to detect on a specified call. When tone monitoring is enabled, detected digits cause the application to be notified with the LINE_MONITORTONE message. This message provides the call handle on which the tone was detected as well as the application's tag for the tone.

The scope of tone monitoring is bound by the lifetime of the call. Tone monitoring on a call ends as soon the call disconnects or goes idle.

Note The monitoring of tones, digits, or media modes often requires the use of resources of which the service provider can only have a finite amount. A request for monitoring can be rejected if resources are not available. For the same reason, an application should disable any unnecessary monitoring.


Media Control

An application can request the execution of a limited set of media-control operations on the call's media stream triggered by telephony events. Although an application is encouraged to use the media API specifically defined for the media mode, media control can yield a significant performance improvement for client/server implementations. The lineSetMediaControl function is used to set up a call's media stream for media control by allowing an application to specify a list of tuples specifying a telephony event and the associated media-control action. The telephony events that can trigger media-control activities are:

  • Detection of a digit The application provides a list of specific digits and the media-control action that each of them triggers.
  • Detection of a media mode The application provides a list of media modes and the media-control actions that a transition into the media mode triggers.
  • Detection of a specified tone The application specifies a list of tones and the media-control action that each tone detection triggers.
  • Detection of a call state The application specifies a list of call states and the media-control action that each transition to the call state triggers.

The media-control actions listed below are defined generically for the different media modes. Not all media streams can provide meaningful interpretations of the media-control actions. The operations should map well to audio streams:

  • Start starts the media stream.
  • Reset resets the media stream.
  • Pause stops or pauses the media stream.
  • Resume starts or resumes the media stream.
  • Rate up increases the rate (speed) of the media stream by an implementation-defined amount.
  • Rate down decreases the rate of the media stream by an implementation-defined amount.
  • Rate normal returns the rate to normal.
  • Volume up increases the volume (amplitude) of the media stream.
  • Volume down decreases the volume of the media stream.
  • Volume normal returns the volume to normal.

The scope of media control is bound by the lifetime of the call. Media control on a call ends as soon the call disconnects or goes idle. Only a single media-control request can be outstanding on a call across all applications.


Digit Gathering

Besides enabling digit monitoring and being notified of digits one at a time, an application can also request that multiple digits be collected in a buffer. Only when the buffer is full or when some other termination condition is met is the application notified. Digit gathering is useful for functions such as credit card number collection. It is performed when an application calls lineGatherDigits, specifying a buffer to fill with digits. Digit gathering terminates when one of the following conditions is true:

  • The requested number of digits has been collected.
  • One of multiple termination digits is detected. The termination digits are specified to lineGatherDigits, and the termination digit is placed in the buffer as well.
  • One of two timeouts expires. The timeouts are a first digit timeout, specifying the maximum duration before the first digit must be collected, and an inter-digit timeout, specifying the maximum duration between successive digits.
  • Digit gathering is canceled explicitly by lineGatherDigits again with either another set of parameters to start a new gathering request or by using a NULL digit buffer parameter to cancel.

When terminated for any reason, a LINE_GATHERDIGITS message is sent to the application that requested the digit gathering. Only a single digit gathering request can be outstanding on a call at any given time across all applications that are owners of the call.

Digit gathering and digit monitoring can be enabled on the same call at the same time. In that case, the application will receive a LINE_MONITORDIGITS message for each detected digit and a separate LINE_GATHERDIGITS message when the buffer is sent back.


Generating Inband Digits and Tones

After a call is in the connected state, information can be transmitted over it. Two functions are provided that allow end-to-end inband signaling between the application and remote station equipment such as an answering machine. One function is lineGenerateDigits, which generates inband digits on a call, signaling them over the voice channel. Digits can be signaled as either rotary/pulse sequences or as DTMF tones. The other function is lineGenerateTone, which enables the application to generate one of a variety of multifrequency tones inband (over the media stream). This generates telephony tones, such as ringback, beep, and busy, as well as arbitrary multifrequency, multicadenced tones.

Only one digit or tone generation can be in progress on a call at any one time. When digit or tone generation completes, a LINE_GENERATE message is sent to the application that requested the generation. In the case where multiple digits are generated, only a single message is sent back after all digits have been generated. Calling lineGenerateDigits or lineGenerateTone while digit or tone generation is in progress will abort the generation currently in progress and send the LINE_GENERATE message to the application whose generation was aborted with a cancel indication.


Call Operations

Call operations include acceptance, rejection, redirecting, holding, forwarding, parking, pickup, and completion. These operations are described in the following topics.


Call Accept, Reject, and Redirect

In environments like ISDN, call offering is separate from alerting. In fact, after a call has been offered to an application, a time window exists during which the application has a number of options:

  • It can immediately answer the call using lineAnswer.
  • It can accept the call using lineAccept, which initiates alerting to both the caller (as ringback) and the called party (as ring).
  • It can reject the offering call using lineDrop, which reverts the offering call to the idle state.
  • It can redirect the call using lineRedirect, which deflects the offering call to another address. The call reverts to the idle state.


Call Hold

Most PBXs can associate multiple calls with a single line. A call can be placed on hard hold, which frees the user's line/address to make other calls. An application can place a call on hard hold by calling lineHold. An application can retrieve a call on hard hold by calling lineUnhold.

Hard hold is different from a consultation hold. A call is automatically placed on consultation hold, for example, when a call is prepared for transfer or conference.


Call Transfer

TAPI provides two mechanisms for call transfer: blind transfer and consultation transfer.

  • In blind transfer (or single-step transfer), an existing call is transferred to a specified destination address in one phase using lineBlindTransfer.
  • In a consultation transfer, the existing call is first prepared for transfer to another address using lineSetupTransfer. This places the existing call on consultation hold, and identifies the call as the target for the next transfer-completion request. The lineSetupTransfer function also allocates a consultation call that can be used to establish the consultation call with the party to which the call will be transferred. The application can dial the extension of the destination party on the consultation call (using lineDial), or it can drop and deallocate the consultation call and instead activate an existing held call (using lineUnhold), if supported by the switch.

While the initial call is on consultation hold and the consultation call is active, the application can toggle between these calls using lineSwapHold.

Finally, the application completes the transfer in one of two ways using lineCompleteTransfer:

  • Transfer the call on transfer hold to the destination party. Both calls will revert to the idle state.
  • Enter a three-way conference. A new call handle is created to represent the conference and this handle is returned to the application.

In TAPI version 2.0 and later, applications can use the "one step transfer" feature of many PBXs (a single button press to establish a consultation transfer) using LINECALLPARAMFLAGS_ONESTEPTRANSFER with lineSetupTransfer.


Call Conference

Conference calls are calls that include more than two parties simultaneously. They can be set up using either a switch-based conference bridge or an external server-based bridge. Typically, only switch-based conferencing will allow the level of conference control provided by the API. In server-based conference calls all participating parties dial into the server which mixes all the media streams together and sends each participant the mix; there may be no notion of individual parties in the conference call, only that of a single call between the application and the bridge server.

A conference call can be established in a number of ways, depending on device capabilities:

  • A conference call can begin as a regular two-party call, such as a call established with lineMakeCall. After the two-party call exists, additional parties can be added, one at a time. Calling lineSetupConference prepares a given call for the addition of another party, and this action establishes the conference call. This operation takes the original two-party call as input, allocates a conference call, connects the original call to the conference, and allocates a consultation call whose handle is returned to the application.

    Note The capabilities of the addressed line device can limit the number of parties conferenced in a single call and whether or not a conference starts out with a normal two-party call.

    The application can then use lineDial on the consultation call to establish a connection to the next party to be added. The lineDrop function can be used to abandon this call attempt. The third party is added with the lineAddToConference function, which specifies both the conference call and the consultation call.

  • A three-way conference call can be established by resolving a transfer request for three-way conference. In this scenario, a two-party call is established as either an incoming or outgoing call. Next the call is placed on transfer hold with the lineSetupTransfer function, which returns a consultation call handle. After a period of consultation, the application may have the option to resolve the transfer setup by selecting the three-way conference option that conferences all three parties together in a conference call with lineCompleteTransfer with the conference option (instead of the transfer option). Under this option, a conference call handle representing the conference call is allocated and returned to the application.
  • A conference call may need to be established with lineSetupConference without an existing two-party call. This returns a handle for the conference call and allocates a consultation call. After a period of consultation, the consultation call can be added with lineAddToConference. Additional parties are added with linePrepareAddToConference followed by lineAddToConference.

To add parties to an existing conference call, the application uses linePrepareAddToConference. When calling this function, the application supplies the handle of an existing conference call. The function allocates a consultation call that can later be added to the conference call and returns a consultation call handle to the application. This conference call is then placed on conference hold. After the consultation call exists, it can be added to the existing conference call with lineAddToConference.

After a call becomes a member of a conference call, the member's call state reverts to conferenced. The state of the conference call typically becomes connected. The call handle to the conference call and all the added parties remain valid as individual calls. LINE_CALLSTATE events can be received about all calls. For example, if one of the members disconnects by hanging up, an appropriate call-state message can inform the application of this fact; such a call is no longer a member of the conference.

As is the case with call transfer, the application can toggle between the consultation call and the conference call using lineSwapHold.

Use the call handle for the member calls to later remove the call from the conference. Do this by calling lineRemoveFromConference on the call handle. This operation is not commonly available in its fully general form. Some switches may not allow it at all, or only allow the most recently added party to be removed. The line's device capabilities describe which type of lineRemoveFromConference is possible.

In TAPI version 2.0 and later, applications can use the "no hold conference" feature of PBXs by using the LINECALLPARAMFLAGS_NOHOLDCONFERENCE option with lineSetupConference; this feature allows another device, such as a supervisor or recording device, to be silently attached to the line.


Removing a Party

When canceling the consultation call to the third party for a conference call or when removing the third party in a previously established conference call, the service provider (and switch) may release the conference bridge and revert the call back to a normal two-party call. If this is the case, hConfCall will transition to the idle state, and the only remaining participating call will transition to the connected state.


Call Park

Two forms of call parking are provided: directed call park and non-directed call park. In directed call park, the application specifies the destination address where the call is to be parked. This roughly behaves like a call transfer to the destination address, but it doesn't alert or time-out as a transfer would.

In non-directed call park, the switch returns to the application the address where it parked the call. In either case, the linePark function is used to park a call. A parked call can later be retrieved with lineUnpark. The application specifies the park address to lineUnpark that returns a call handle to the unparked call. Appropriate LINE_CALLSTATE messages will be sent to the application as the call is reconnected.


Call Forwarding

Forwarding affects how the switch or network treats incoming calls destined for a given address. The application can specify call forwarding conditions based on the origin of the call (internal, external, selective based on caller ID); the status of the address (busy, no answer, unconditionally); and the destination address where calls are to be forwarded. When the specified conditions are met for an incoming call, the switch deflects the incoming call to the specified destination number. Because the switch performs the forwarding action, the application will typically not know when a call has been forwarded.

The lineForward function provides a combination of call forwarding (by setting call-forwarding requests) and a do-not-disturb feature. The lineForward function can also cancel any or all of the forwarding requests currently in effect. Some switches require that a call be established to the forwarding address for call forwarding to be initiated. On such systems, lineForward allocates a consultation call and returns the handle for it to the application. The consultation call can be used as any other call. After the connection is established, forwarding confirmation is received from the switch, the call is dropped (using lineDrop), and forwarding is in effect. A LINE_ADDRESSSTATE message with a forwarding indication informs the application about changes in the forwarding status of an address.

Note It may be impossible for a service provider to know at all times what forwarding is in effect for an address. Forwarding can be canceled or changed in ways that make it impossible for a service provider to be informed of this fact.


Call Pickup

Call pickup allows an application to answer a call that is alerting at another address. The application invokes linePickup by identifying the target of the pickup and is returned a call handle for the picked-up call. There are several ways to specify the target of the pickup request. First, specify the address (extension) of the alerting party. Second, if no extension is specified and the switch allows it, the application can pick up any ringing phone in its pickup group. Third, some switches require a group identifier to identify the group to which the ringing extensions belongs.

After the call has been picked up, it is diverted to the application and the application is sent appropriate LINE_CALLSTATE messages for the call. An application can invoke lineGetCallInfo for information about the picked-up call, if provided by the switch.

Some key telephone systems support a transfer through hold capability on bridged-exclusive call appearances. In this scheme, a call is owned exclusively by a particular phone when it is active, but when the call is on hold it can be picked up on any phone that has an appearance of the line. In TAPI version 2.0 and later, an application can use the linePickup function with a NULL target address for this purpose, similar to how the function is used to pick up a call waiting call on an analog line. LINEADDRFEATURE_PICKUPHELD indicates the existence of the capability (in LINEADDRESSCAPS) and when it can be invoked (in LINEADDRESSSTATUS).


Call Completion

When making an outbound call, the unavailability of certain resources can prevent the call from reaching the connected state, as when the destination party is busy or doesn't answer. Unavailable resources include trunk circuits as well as the destination party's station. The lineCompleteCall function lets the application specify how it wants to complete a call that cannot be completed normally—this is called "placing a call-completion request." The application has the following options:

  • Camp on queues the call until the call can be completed.
  • Call back requests the called station to return the call when the station returns to idle. Answering the call-back can automatically reinitiate (redial) the connection request.
  • Intrude allows the application to barge in to the existing call.
  • Message (also known as "leave word calling") allows the application to send one of a small number of predefined messages to the destination. These messages can be text shown on the phone's display, a voice message left for the user, and so forth.

A call completion request can be canceled with lineUncompleteCall. Multiple call completion requests can potentially be outstanding for a given address at any one time. To identify individual requests, the implementation returns a completion identifier. When a call completion request completes and results in a new call, the call completion identifier is available in the LINECALLINFO data structure returned by lineGetCallInfo. Canceling a call completion request in progress also uses this call completion identifier.

In TAPI version 2.0 and later, the LINECALLREASON_CAMPEDON bit allows a service provider to indicate when a new call was camped on to an address.


Extended Line Functions

Extended Line Services (or device-specific line services) include all service-provider defined extensions to the API. The API defines a mechanism that enables service-provider vendors to extend TAPI using device-specific extensions. The API only defines the extension mechanism, and by doing so provides access to device-specific extensions, but the API does not define their behavior. Behavior is completely defined by the service provider.

TAPI consists of scalar and bit-flag constant definitions, data structures, functions, and messages. Procedures are defined that enable a vendor to extend most of these as follows.

For extensible scalar data constants, a service-provider vendor can define new values in a specified range. As most data constants are DWORDs, typically the range 0x00000000 through 0x7FFFFFFF is reserved for common future extensions, while 0x80000000 through 0xFFFFFFFF are available for vendor-specific extensions. The assumption is that a vendor would define values that are natural extensions of the datatypes defined by the API.

For extensible bit-flag data constants, a service-provider vendor can define new values for specified bits. As most bit-flag constants are DWORDs, typically a specific number of the lower bits are reserved for common extensions while the remaining upper bits are available for vendor-specific extensions. Common bit flags are assigned from bit zero up; vendor-specific extensions should be assigned from bit 31 down. This provides maximum flexibility in assigning bit positions to common extensions versus vendor-specific extensions. A vendor is expected to define new values that are natural extensions of the bit flags defined by the API.

Extensible data structures have a variably sized field that is reserved for device-specific use. Being variably sized, the service provider decides the amount of information and the interpretation. A vendor that defines a device-specific field is expected to make these natural extensions of the original data structure defined by the API.

Two functions, lineDevSpecific and lineDevSpecificFeature, and two related messages, LINE_DEVSPECIFIC and LINE_DEVSPECIFICFEATURE, provide a vendor-specific extension mechanism. The lineDevSpecific function and associated LINE_DEVSPECIFIC message enable an application to access device-specific line, address, or call features that are unavailable with the Basic or Supplementary Telephony Services. The parameter profile of the lineDevSpecific function is generic in that little interpretation of the parameters is made by the API. The interpretation of the parameters is defined by the service provider and must be understood by an application that uses them. The parameters are simply passed through TAPI from the application to the service provider. An application that relies on device-specific extensions will not generally work with other service providers; however, applications written to the Basic and Supplementary Telephony Services will work with the extended service provider.

For convenience, a more specialized escape function is also provided. It is similar to lineDevSpecific, but places interpretation on some of the parameters. This more specialized function is lineDevSpecificFeature, a device-specific escape function to allow sending switch features to the switch. The message LINE_DEVSPECIFICFEATURE is the device-specific message sent to the application as an indication of features sent to the switch. This function and its associated message allow an application to emulate button presses at the line's feature phone. As feature phones and the meanings of their buttons are vendor-specific, feature invocation using lineDevSpecificFeature is also vendor specific.

As mentioned earlier, there is no central registry for manufacturer identifiers. Instead, a unique identifier generator (EXTIDGEN) is made available.


Passthrough Mode

When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. Applications can use this mode for temporary direct control over asynchronous modems, accessed through the Win32 Communication functions, for the purpose of configuring or using special features not otherwise supported by the service provider, such as facsimile (Class 1, 2, and so on). This bearer mode is supported by the Universal Modem Driver (UNIMODEM) service provider.

Service providers that support LINEBEARERMODE_PASSTHROUGH indicate it in the dwBearerModes member of the LINEDEVCAPS structure. When LINEBEARERMODE_PASSTHROUGH is indicated, the Unimodem service provider will also include in the DevSpecific area of the LINEDEVCAPS structure the registry key used to access information about the modem associated with the line device, in the following format:

struct {
    DWORD dwContents;   // Set to 1 (indicates containing key)
    DWORD dwKeyOffset;  // Offset to key from start of this
                        // structure (not from start of
                        // LINEDEVCAPS structure). 8 in
                        // our case.
    BYTE rgby[...];     // place containing null-terminated
                        // registry key.
}

For example:

00000001 00000008 74737953 435c6d65  ........System\C
    65727275 6f43746e 6f72746e 7465536c  urrentControlSet
    7265535c 65636976 6c435c73 5c737361  urrentControlSet
    65646f4d 30305c6d xx003030 xxxxxxxx  Modem\0000.

This registry key could then be opened using this function:

RegOpenKey(HKEY_LOCAL_MACHINE, pszDevSpecificRegKey, &phkResult)

Passthrough mode is invoked most often using the lineMakeCall function, by setting the LINEBEARERMODE_PASSTHROUGH bit in the dwBearerMode member of the LINECALLPARAMS structure pointed to by the lpCallParams parameter. When this is done, the service provider will open the serial port to the modem and immediately place the call into LINECALLSTATE_CONNECTED. The application can then use the lineGetID function with the device class "comm/datamodem" to obtain an open Win32 file handle to read from and write to the comm port.

Passthrough mode can be invoked in response to an incoming call as well. Generally, applications will invoke passthrough mode while the call is in LINECALLSTATE_OFFERING, before the call has been answered. Instead of calling lineAnswer, the application calls lineSetCallParams, passing LINEBEARERMODE_PASSTHROUGH as the dwBearerMode parameter. When this is done, as with lineMakeCall, the call will immediately be placed into LINECALLSTATE_CONNECTED by the service provider, and the application can obtain a handle to the open port using lineGetID. The lineSetCallParams function can be called when the call is in LINECALLSTATE_OFFERING, LINECALLSTATE_ACCEPTED, or LINECALLSTATE_CONNECTED.

Passthrough mode is normally terminated by calling lineDrop on the call handle obtained from lineMakeCall or the first LINE_CALLSTATE message (if the call was an incoming call). The service provider will close the port, and restore the modem to its default state. The application must call CloseHandle on the handle it received from lineGetID.

Passthrough mode can also be terminated by calling lineSetCallParams with the dwBearerMode parameter set to LINEBEARERMODE_VOICE. The media mode set by lineSetMediaMode is presumed to be in effect. If LINEMEDIAMODE_DATAMODEM is active, the service provider will take over the call as though it was a data modem call already in progress; if lineDrop is subsequently called, the service provider will issue the appropriate modem commands or interface state changes to drop a data call.


Quality of Service

As Asynchronous Transfer Mode (ATM) networking emerges into the mainstream of computing, and support for ATM has been added to other parts of the Microsoft® Windows® operating system, TAPI also supports key attributes of establishing calls on ATM facilities. The most important of these from an application perspective is the ability to request, negotiate, renegotiate, and receive indications of Quality of Service (QOS) parameters on incoming and outgoing calls.

QOS information in TAPI is exchanged between applications and service providers in FLOWSPEC structures that are defined in Windows Sockets 2.0.

Applications request QOS on outgoing calls by setting values in the flowspec fields in the LINECALLPARAMS structure. The service provider will endeavor to provide the specified QOS, and fail the call if it cannot; the application can then adjust its parameters and try the call again. After a call is established, an application can use the lineSetCallQualityOfService function to request a change in the QOS; a new bit, LINECALLFEATURE_SETQOS, lets applications determine when this function can be called.

The QOS applicable to incoming or active calls can be obtained by using lineGetCallInfo and examining the flowspec fields. A bit in the LINE_CALLINFO message, LINECALLINFOSTATE_QOS, lets applications know when QOS information for a call has been updated.

Support for QOS is not restricted to ATM transports; any service provider can implement QOS features.


Call Center Control

You can use TAPI to manage call centers and other elements of Telephony network infrastructure (such as IVR and voice mail servers) through third-party call control. The following topics describe the TAPI features that make this control easier.


Modeling of a Call Center

Service providers can expose each resource on the PBX as a line device and possibly an associated phone device. Terminals that support multiple call appearances would do so through multiple addresses, just as in first-party call control. In fact, the third-party view of a device is identical to the first-party view; applications on the server can see and control all of the first-party devices, whereas an individual client PC connected to the server can only see those devices that are made visible to it through access controls administered by tapisrv.exe on the server. Resources other than terminals can also be modeled as line devices. For example, an ACD queue or route point would be modeled as a line device that could have many active calls; an IVR server, voice mail server, or set of predictive dialing ports could also be modeled as a line device that supports multiple calls.

Within this model, the status of the addressed device and calls associated with it can be monitored though existing TAPI messages such as LINE_LINEDEVSTATE, LINE_ADDRESSSTATE, LINE_CALLSTATE, and LINE_CALLINFO, and details obtained through functions such as lineGetLineDevStatus, lineGetAddressStatus, lineGetCallStatus, and lineGetCallInfo. Whenever a TAPI object is operated upon through a third-party application running on the server, the result is identical to what would have occurred if the same object had been similarly operated on by a first-party application running on a client PC associated with that device. Status indications sent by the server service provider controlling the switching fabric (or switch) are delivered both to applications running on the server and to those running on associated, authorized clients.


Stations

Station sets being monitored through a third-party link are modeled as a line device and possibly an associated phone device. The line device can have multiple addresses, if the modeled terminal supports more than one directory number (DN). Multiple call appearances on the same DN can be modeled as a single address that supports multiple calls.

Calls between two stations on the switch have two call handles, one giving the call view from the first station (on its line device), and the other giving the call view from the second station (on its line device). For example, a third-party lineMakeCall placed by an application on the server would be directed to the line device associated with the station from which the call is to be dialed; a call handle would be created on that line, on the address specified in LINECALLPARAMS (thereby giving control over which DN is used on a phone that supports multiple DNs). When the call is offered to the destination address, a new call handle showing a call in offering state is created; applications would know that it was another view of the same call by the dwCallID member in LINECALLINFO being equal for both calls. Both calls would go idle when the call was dropped; a call could be dropped from the third-party application by doing a lineDrop on either of the call handles.


Predictive Dialing

Predictive dialing is an application that typically runs on a call center telephony server. It uses a list of phone numbers, often obtained from a database, to attempt outgoing calls; when a call is completed, the call is automatically assigned to an agent for handling. The application can make use of a predictive dialing port on a switch, which is a device that can make outgoing calls and has special abilities (through DSP, and so on) to detect call progress tones and other audible indications of call state. When a call is made on a predictive dialing port, typically it is automatically transferred to another device on the switch when the call reaches a particular state or upon detection of a particular media mode; this target device can be a queue for agents handling outgoing calls.

Applications identify a device as having predictive dialing capability by the LINEADDRCAPFLAGS_PREDICTIVEDIALER bit in the dwAddrCapFlags member in LINEADDRESSCAPS. The dwPredictiveAutoTransferStates member in LINEADDRESSCAPS indicates the states upon which the predictive dialing port can be commanded to automatically transfer a call; if this member is zero, it indicates that automatic transfer is not available, and that it is the responsibility of the application to transfer calls explicitly upon detecting the appropriate call state (or media mode or other criteria). Preferably, switch manufacturers will make available both automatic and manual transfer, and allow applications to select the preferred mechanism, but service providers would have to model the behavior of legacy equipment. A single predictive dialing port (line device/address) can support making several outgoing calls simultaneously, as indicated by the dwMaxNumActiveCalls member in LINEADDRESSCAPS. Predictive dialing capability can also be made available on any device, using a shared pool of predictive dialing signal processors, which are bridged onto the line being dialed upon request.

When the lineMakeCall function is used on a line capable of predictive dialing (a port with the LINEADDRCAPFLAGS_PREDICTIVEDIALER set) and predictive dialing is requested using LINECALLPARAMFLAGS_PREDICTIVEDIAL, then the call is made in a predictive fashion with enhanced audible call progress detection. Additional fields and constants are defined in the LINECALLPARAMS structure passed in to lineMakeCall to control the behavior of the predictive dialing port. The dwPredictiveAutoTransferStates member indicates the line call states which, upon entry of the call into any of them, the predictive dialing port should automatically transfer the call to the designated target (the bits must be a proper subset of the supported auto-transfer states indicated in LINEADDRESSCAPS); the application can leave the field set to 0 if it desires to monitor call states itself and use lineBlindTransfer to transfer the call when it reaches the desired condition. The application must specify the desired address to which the call should be automatically transferred in the variable field defined by the dwTargetAddressSize and dwTargetAddressOffset members in LINECALLPARAMS.

Applications can also set a timeout for outgoing calls so that the service provider automatically transitions them to a disconnected state if they are not answered. This is controlled using the dwNoAnswerTimeout member in LINECALLPARAMS.


Call Queues and Route Points

A call queue or route point is a special address within the switch where calls are temporarily held pending action. This characteristic is represented by the bits LINEADDRCAPFLAGS_QUEUE and LINEADDRCAPFLAGS_ROUTEPOINT in the dwAddrCapFlags member in LINEADDRESSCAPS. All calls appearing on such an address are awaiting action by the application, and there can be default actions that take place (for example, transfer to an agent or trunk) if the application takes no action within a defined period of time. The application must be configured by the system administrator so that it knows what actions it should take regarding calls appearing on each queue or route point address, and the amount of time available to decide on the action to take.

Applications can determine the number of calls pending in a queue or route point using lineGetAddressStatus. The lineGetCallInfo function can be used to obtain information such as calling ID, called ID, incoming or outgoing origin, and so on, and used by the application to make decisions on call handling; calls can be redirected, blind-transferred, dropped, and so on, or just allowed to automatically pass out of the queue to a destination. A call goes to LINECALLSTATE_DISCONNECTED if it is abandoned. Calls go idle when they leave the queue; lineGetCallInfo can be used to read the redirection identifier to determine where they were transferred.

Some switches allow calls in a queue or on hold to receive particular treatment such as silence, ringback, busy signal, music, or listening to a recorded announcement. The lineSetCallTreatment function allows the application to control the treatment. The structure delimited by the dwCallTreatmentListSize and dwCallTreatmentListOffset members in LINEADDRESSCAPS allows applications to determine the supported treatments. The dwCallTreatment member in LINECALLINFO indicates the current treatment, and a LINE_CALLINFO message with LINECALLINFOSTATE_TREATMENT indicates when this changes. The LINECALLFEATURE_SETTREATMENT bit in the dwCallFeatures member in LINECALLSTATUS indicates when the application is permitted to change the treatment. The LINECALLTREATMENT_ set of constants defines a limited set of predefined call treatments; service providers can define many more.


ACD Agent Monitoring and Control

Monitoring and control of ACD agent status on stations is supported through these functions: lineGetAgentCaps, lineGetAgentStatus, lineGetAgentGroupList, lineGetAgentActivityList, lineSetAgentGroup, lineSetAgentState, and lineSetAgentActivity. The LINE_AGENTSTATUS message is used to indicate when agent information has changed.

These controls are associated with an address instead of a line because many ACD systems are implemented with different ACD queues associated with buttons on the phone terminal (and separate call appearances). Also, ACD agent phones can often have separate call appearances for personal calls.

Architecturally, ACD functionality should be implemented in a server-based application. The client functions mentioned above, rather than mapping to the telephony service provider, are conveyed to a server application that has registered (using an option of lineOpen) as a handler for such functions. The LINE_PROXYREQUEST message is used to signal to the handler application when a request has been made; it calls the lineProxyResponse function to return results and data. Handler applications can also call lineProxyMessage to generate LINE_AGENTSTATUS messages when required. In the case of a legacy PBX or stand-alone ACD that implements ACD functionality itself, the telephony service provider for the switch must include a proxy server application that accepts the requests and routes them (possibly using lineDevSpecific functions or a private interface) to the service provider, which routes them to the switch.


Call Data

In a call center environment, applications may need to accumulate data about a call (such as IVR input of account numbers) that is desirable to have available to all agents and applications that handle the call. The variably-sized field, bounded by the dwCallDataSize and dwCallDataOffset members in the LINECALLINFO structure, gives the telephony application a way to provide to the service provider data to be passed along with a transferred call and made visible to other applications that are monitoring the call (either on the same PC, or, through the server, on other PCs). The LINECALLINFOSTATE_CALLDATA message indicates whenever this field changes. The lineSetCallData function allows an application that owns the call to set this data; LINECALLFEATURE_SETCALLDATA indicates when changing the data is permitted. The dwMaxCallData member in LINEADDRESSCAPS indicates the maximum number of bytes permitted in this field. Initial call data to be attached to a call can be passed to the service provider in LINECALLPARAMS.


Station Status Control

There are three major station status functions that need control: Message Waiting lights, Forwarding, and Do Not Disturb. Forwarding and Do Not Disturb are controllable through the existing lineForward function (which is address-specific), and queried using lineGetAddressStatus. The LINEDEVSTATUSFLAGS_MSGWAIT bit in the dwDevStatusFlags member of LINEDEVSTATUS indicates the status of the message waiting light on the device, and a LINEDEVSTATE_MSGWAITON or LINEDEVSTATE_MSGWAITOFF message is sent to indicate when the state changes. The lineSetLineDevStatus function allows the message waiting light to be controlled without having to implement a TAPI phone device just for that purpose. The LINEFEATURE_SETDEVSTATUS bit (in the dwLineFeatures member of LINEDEVCAPS and LINEDEVSTATUS) indicates when it can be called, and the dwSettableDevStatus member of LINEDEVCAPS allows the application to detect which device status settings can be controlled from the application. In addition to allowing the message waiting feature to be controlled, it also allows the device's Connected, Inservice, and Locked status to be set, to the extent that these are supported by the switch or other hardware. Calls to this function result in appropriate LINE_LINEDEVSTATE messages being sent to reflect the new status.


Call State Timer

Currently, all timing of calls is left up to applications. This can be burdensome if the application is monitoring a large number of calls, and if multiple applications are present, possibly on multiple servers, it can be necessary for them to all maintain timers on the same calls. It therefore makes more sense for call state timing to be handled by the server.

The tStateEntryTime member in LINECALLSTATUS allows timing of calls in states to be reported. The member (of type SYSTIME) indicates the time at which the current state was entered.


Media Event Timers

Many applications depend on the timing relationship between media events (for example, DTMF digits received) in order to determine the nature of a requested operation. For example, in a voice mail application, two consecutive DTMF "1" digits may mean "back up two segments" or "replay from beginning of message", depending on how much time elapsed between the two digits. In a client/server environment, if the DTMF detection is being performed on a separate processor from the one on which the application is running, latency in the local area network makes it very likely that the timing relationship between media events will be skewed, with the result that these timing-based differences could be lost or become unreliable.

To resolve this issue, several TAPI messages can be timestamped. Because it is the relative timing between these events that is important, the "clock time" of the event is not important, and sub-second timing is involved, these timestamps use the millisecond-resolution "time since Windows started" returned by the GetTickCount function. Applications must be aware that this is the tick count on the server (or machine where the service provider directly managing the hardware is running), and is not necessarily the same machine on which the application is executing; thus, the timestamps in these TAPI messages can only be compared to each other, and not to the value returned by GetTickCount on the processor on which the application is running.

The TAPI messages that can be timestamped are: LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORMEDIA, and LINE_MONITORTONE. The tick count is inserted into dwParam3 of these messages. If timestamping is not supported by the service provider (which is indicated by the service provider setting dwParam3 in these messages to 0), then TAPI itself will insert the tick count into dwParam3 of all of these messages (it can be skewed somewhat, but less than if the application did the same after the messages had traversed an interprocess communication scheme).


Line Devices Overview

A line device is a physical device such as a fax board, a modem, or an ISDN card that is connected to an actual telephone line. Line devices support telephonic capabilities by allowing applications to send or receive information to or from a telephone network. A line device is the logical representation of a physical line device, one of the two device classes supported by TAPI. This section describes line devices and explains how to use the line functions that access these devices.


What is a Line Device?

A line device is a physical device such as a fax board, a modem, or an ISDN card that is connected to an actual telephone line (although the device may not be physically connected to the computer on which the telephony application is running). Line devices support telephonic capabilities by allowing applications to send or receive information to or from a telephone network. A line device contains a set of one or more homogeneous channels that can be used to establish calls.

Within TAPI applications, a line device is the logical representation of a physical line device. Although "line" often connotes something with two endpoints, it is possible to abstract a line device to a single point because TAPI views it only as a point of entry to the line that leads to the switch.

Although the three lines in the preceding illustration are composed of different hardware and used for different functions, they are abstracted to the same device type and governed by the same rules. The telephone represents not a phone device but a line device used for voice calls. When using this line device for incoming or outgoing calls, the application would also need to open and control an instance of the phone-device class, which is described in detail in later sections.

TAPI requires that every TAPI-capable line device support all of Basic Telephony. If an application needs to use capabilities beyond those of Basic Telephony (namely Supplementary or Extended Telephony), it must first determine the line device's capabilities, which can vary according to network configuration (client versus client/server), hardware, service-provider software, and the telephone network. The lineNegotiateAPIVersion function allows the application to identify the set of Extended capabilities supported on a line device, and the lineNegotiateExtVersion function allows for different versions of that set to be used. The lineGetDevCaps function returns the telephonic capabilities implemented through the use of the Supplementary and Extended (if any) TAPI functions of a given line device in a data structure of the type LINEDEVCAPS.


Lines, Channels, and Addresses

In POTS, exactly one channel exists on a line, and is used exclusively for voice. With ISDN, at least three (and as many as 30 or more) channels can exist on a line simultaneously. Currently, most TAPI functionality involves POTS applications that handle a single line using its single channel because ISDN hardware is not yet widespread. In POTS, an application that wants to transmit data communicates over one line, and a voice application communicates over another line—both of these applications could use the same line, but if so, not at the same time.

In general, one line has exactly one address (telephone number). In cases where lines carry two or more channels, each channel can have its own address, which means that a line has as many addresses as it has channels. TAPI assigns address identifiers to these different addresses to make it easier to manipulate them.


Multiple Addresses on a Single Channel

Some installations support the assignment of more than one address to a single channel. On POTS lines, multiple addresses are made possible by various systems, such as DID (direct inward dialing) or distinctive ringing, which are extra-fee services provided by the telephone company.

Many large corporations use DID for incoming calls. Before a call is connected, its destination extension number is signaled to the PBX, which causes the extension to ring instead of the operator's phone. An example of distinctive ringing in a private home would be if the parents used one address, the children another, and a fax machine a third. Because only one line connects the house to the telephone network, all phones ring when a call appears, but the ring pattern is different depending on the number dialed by the calling party. With distinctive ringing, the people know who the incoming call is for, and the fax machine answers its calls by recognizing its own ringing style.

In ISDN, the various B channels might not have separate addresses. Because these B channels might be on the same address, it is the service provider (and not the application or a person who has dialed the number) that assigns calls to these channels.


ISDN Subaddresses

Subaddressing is a capability provided on ISDN lines that allows more information than just a single telephone number to be used when dialing. This additional information can specify an individual telephone extension to ring or, in a computing environment, a particular application to be alerted. Other parameters that can be passed can describe the required aspects of a requested modem connection, such as rate and timing.


Addresses and Address Identifiers

Each line device is assigned one or more addresses. An address corresponds to a telephone directory number, and it is actually assigned twice: First, by the telephone company at the switch, and second, by the user while configuring the local system. If a telephone number is changed at the switch, the user will normally need to assign the new number at the local system, although some systems can be sophisticated enough to perform the reassignment without human control.

After addresses have been assigned to lines, TAPI assigns address identifiers to addresses. An address identifier is a number between 0 and the number of addresses on the line minus one. Because each address depends on its line to exist, the address's identifier is meaningful only in the context of the associated line device. For this reason, an address name consists of not only the address identifier, but also an identifier of the line. It serves as a kind of shorthand, an easy way for programmers to identify addresses.


Address Configurations

The relationship of an address to a line (and to other local addresses) is known as its configuration. The network or switch can configure address-to-line assignments in several ways. The main types of address configurations recognized by TAPI are:

  1. Private The address is assigned to one line device only. An incoming call for this address is offered (the switch informs the desktop computer of an incoming call) at one line device only.
  2. Bridged A bridged address is a single address assigned to more than one line device. (Different switch vendors have different names for address bridging, such as multiple appearance directory number (MADN), bridged appearance, or shared appearance.) An incoming call on a bridged address is offered on all lines associated with the address. The network of lines connected together is known as the bridge. Different variations of bridged behavior are possible:
    • Bridged-Exclusive Connecting one of the bridged lines to a remote party causes the address to appear "in use" to all other members of the bridge.
    • Bridged-New Connecting one of the bridged lines to a remote party does not preclude the other lines from using the bridged address to answer or make calls. However, a new call appearance is allocated to another of the connected lines.
    • Bridged-Shared If one line is connected to a remote party, other bridged lines that use the address automatically enter into a multiparty conference call on the existing call.
  3. Monitored The line indicates the busy or idle status of the address, but the line cannot use the address for answering or making calls.


Address-Related Functions and Messages

Different line devices can have different capabilities and so can their addresses. Additionally, switching features and capabilities can be different for different addresses. An application calls the lineGetAddressCaps function to determine the telephony capabilities of each address and then receives this information in a data structure of the type LINEADDRESSCAPS. In a similar way, an application can call lineGetDevCaps for a line device to determine the number of addresses assigned to the line, as well as other information.

TAPI's device-query capability and status and event reporting mechanisms give an application the information it needs to manage the different kinds of bridged-address arrangements. For example, the application can determine whether a bridged station has answered a call by tracking the status changes and call-state event changes on the address. (For more information about call states, see Call States and Events.)

Normally, addresses on a line device are identified by their address identifiers. However, TAPI lets applications that make outgoing calls use alternate address types for the originating address, such as dialable format (see Address Formats), or naming mechanisms specific to a given service provider. This can be accomplished through API extensions that are based on switch-assigned station identifiers. A useful function for this purpose is lineGetAddressID, which retrieves the identifier of an address specified in an alternate format.


Address Formats

Each address identifier corresponds to a directory number through which incoming calls can be placed to the address. Similarly, making outgoing calls typically requires that a directory number—the address—be supplied to identify the party being called.


Storing Numbers in Electronic Address Books

Many users choose to dial people, fax machines, bulletin boards, and other entities by selecting their names from an address book. The actual number that is dialed depends on the geographic location of the user and the way the line device to be used is connected. For example, a desktop computer can have access to two lines, one connected to a PBX, the other to the telephone company's central office. When making a call to the same party, different numbers may have to be used. (To dial through the PBX, for example, the computer may need to dial '9' to "get out," or a different prefix may be needed for a call made through the central office.) Or, a user may make calls from a portable computer and want to use a single, static address book even when calling from different locations or telephony environments. TAPI's address translation capabilities let the user inform the computer of the current location and the desired line device for the call. TAPI then handles any dialing differences, requiring no changes to the user's address book. An application uses the lineTranslateAddress function to convert an address from the canonical address format to the dialable address format (see Canonical Addresses).

A related topic is the handling of international call-progress monitoring, which is the process of listening for audible tones such as dial tone, special information tones, busy signals, and ringback tones to determine the state of a call (its progress through the network). Because the cadences and frequencies of call-progress tones vary from country to country, the service provider must know what call progress to follow when making an international outgoing call. Therefore, applications specify the destination country code when placing outgoing calls.


Canonical Addresses

The canonical address format is intended to be a universally constant directory number. For this reason, numbers in address books are best stored using canonical format. A canonical address is an ASCII string with the following structure:

+ CountryCode Space [(AreaCode) Space] SubscriberNumber | Subaddress ^ Name CRLF ...

The components of this structure are described in the following table.

Component | Meaning
+ | Equivalent to ASCII Hex (2B). Indicates that the number that follows it uses the canonical format.
CountryCode | A variably sized string containing one or more of the digits "0" through "9". The CountryCode is delimited by the following Space. It identifies the country in which the address is located.
Space | Exactly one ASCII space character (0x20). It is used to delimit the end of the CountryCode part of an address.
AreaCode | A variably sized string containing zero or more of the digits "0" through "9". AreaCode is the area code part of the address and is optional. If the area code is present, it must be preceded by exactly one ASCII left parenthesis character (0x28), and be followed by exactly one ASCII right parenthesis character (0x29) and one ASCII Space character (0x20).
SubscriberNumber | A variably sized string containing one or more of the digits "0" through "9". It may include other formatting characters as well, including any of the dialing control characters described in the Dialable Address Format: AaBbCcDdPpTtWw*#!,@$? The subscriber number should not contain the left parenthesis or right parenthesis character (which are used only to delimit the area code), nor should it contain the "|", "^", or CRLF characters (which are used to begin following fields). Most commonly, nondigit characters in the subscriber number would include only spaces, periods ("."), and dashes ("-"). Any allowable nondigit characters that appear in the subscriber number are omitted from the DialableString returned by the lineTranslateAddress function, but are retained in the DisplayableString.
| | ASCII Hex (7C). If this optional character is present, the information following it up to the next + | ^ CRLF, or the end of the canonical address string is treated as subaddress information, as for an ISDN subaddress.
Subaddress | A variably sized string containing a subaddress. The string is delimited by + | ^ CRLF or the end of the address string. During dialing, subaddress information is passed to the remote party. It can be such things as an ISDN subaddress or an e-mail address.
^ | ASCII Hex (5E). If this optional character is present, the information following it up to the next CRLF or the end of the canonical address string is treated as an ISDN name.
Name | A variably sized string treated as name information. Name is delimited by CRLF or the end of the canonical address string and can contain other delimiters. During dialing, name information is passed to the remote party.
CRLF | ASCII Hex (0D) followed by ASCII Hex (0A), and is optional. If present, it indicates that another canonical number is following this one. It is used to separate multiple canonical addresses as part of a single address string (inverse multiplexing). For example, the canonical representation of the main switchboard telephone number at Microsoft Corporation would be: +1 (425) 882-8080


Dialable Addresses

The dialable address format describes a number that can be dialed on the given line. A dialable address contains part addressing information and is part navigational in nature. Any input string that does not begin with a "+" character is presumed to be not in canonical format and therefore in dialable address format, and is returned to the application unmodified. A dialable address is an ASCII string with the following structure:

DialableNumber | Subaddress ^ Name CRLF ...

The components of this structure are given in the following table.

Component | Meaning
DialableNumber | Digits and modifiers 0-9 A-D * # , ! W w P p T t @ $ ? ; delimited by | ^ CRLF or the end of the dialable address string. The plus sign (+) is a valid character in dialable strings. It indicates that the phone number is a fully-qualified international number. Within the DialableNumber, note the following definitions: 0-9 A-D * # ASCII characters corresponding to the DTMF and/or pulse digits.
! | ASCII Hex (21). Indicates that a hookflash (one-half second onhook, followed by one-half second offhook before continuing) is to be inserted in the dial string.
P p | ASCII Hex (50) or Hex (70). Indicates that pulse dialing is to be used for the digits following it.
T t | ASCII Hex (54) or Hex (74). Indicates that tone (DTMF) dialing is to be used for the digits following it.
, | ASCII Hex (27). Indicates that dialing is to be paused. The duration of a pause is device specific and can be retrieved from the line's device capabilities. Multiple commas can be used to provide longer pauses.
W w | ASCII Hex (57) or Hex (77). An uppercase or lowercase W indicates that dialing should proceed only after a dial tone has been detected.
@ | ASCII Hex (40). Indicates that dialing is to "wait for quiet answer" before dialing the remainder of the dialable address. This means to wait for at least one ringback tone followed by several seconds of silence.
$ | ASCII Hex (24). Indicates that dialing the billing information is to wait for a "billing signal" (such as a credit card prompt tone).
? | ASCII Hex (3F). Indicates that the user is to be prompted before continuing with dialing. The provider does not actually do the prompting, but the presence of the "?" forces the provider to reject the string as invalid, alerting the application to the need to break it into pieces and prompt the user in-between.
; | ASCII Hex (3B). If placed at the end of a partially specified dialable address string, it indicates that the dialable number information is incomplete and more address information will be provided later. The ";" component is only allowed in the DialableNumber portion of an address.
| | ASCII Hex (7C), and is optional. If present, the information following it up to the next + | ^ CRLF, or the end of the dialable address string is treated as subaddress information (as for an ISDN subaddress).
Subaddress | A variably sized string containing a subaddress. The string is delimited by the next + | ^ CRLF or the end of the address string. When dialing, subaddress information is passed to the remote party. It can be for an ISDN subaddress, an e-mail address, and so on.
^ | ASCII Hex (5E), and is optional. If present, the information following it up to the next CRLF or the end of the dialable address string is treated as an ISDN name.
Name | A variably sized string treated as name information. Name is delimited by CRLF or the end of the dialable address string. When dialing, name information is passed to the remote party.
CRLF | ASCII Hex (0D) followed by ASCII Hex (0A). If present, this optional character indicates that another dialable number is following this one. It is used to separate multiple dialable addresses as part of a single address string (for inverse multiplexing).

The lineTranslateAddress function and related support functions are used to translate an address from canonical format to dialable format. An application might not use this function to dial a number but it might use it to generate and display for verification a number that could be dialed. Also, it can compute the local time at the destination address from the country code and area code.

The application uses lineTranslateAddress to specify both the line device upon which it intends to dial the call and a canonical address, and the function returns the dialable number and the country code. Because the line device can have specific dialing requirements, it is part of the context needed for an accurate translation.

The user's location also plays a role in address translation. Information related to the current location, such as the country code, area code, and outside line access codes is entered by the user through the Telephony Control Panel. The Subaddress and Name fields, if present in the address, are unmodified by the translation. Alphabetic characters in the number, such as in 1-800-FOR-TAPI, are not translated by the lineTranslateAddress function due to the different standardizations in use in different countries, but they may be translated by applications themselves.

Although an application can use dialable addresses returned by lineTranslateAddress, it is not limited to them and can compose its own dialable numbers.


Initialization and Shutdown in TAPI

For an application to use any of TAPI's basic or supplementary line functions, it needs a connection to TAPI through which it can receive messages. The application establishes this connection, using either the lineInitializeEx or the phoneInitializeEx function. The parameters of these functions allow the application to specify the message notification mechanism the application desires to use. Following are specifics about the initialization process:

  • The initialization functions are not device-related. When an application calls an initialization function, TAPI does not act on a line or phone device or an abstraction thereof.
  • The first time an initialization function is called in a telephony session, TAPI also sets up the telephony environment. Among the tasks it performs are loading the TAPI dynamic-link library and tapisrv.exe, and loading the device drivers (telephony service providers and ancillary components) specified in the registry. In addition, the communication link described above is established between TAPI and the calling application.
  • The INIFILECORRUPT error can be returned if TAPI determines that the registry contains an invalid entry. When this error occurs (in lineInitializeEx and phoneInitializeEx, or another function), the user should identify and resolve the problem. It may be necessary to rebuild the registry or a portion of it, which can be done through the Telephony Control Panel.

    For example, the LINEERR_NODRIVER ("the driver was not installed") error indicates either that a service provider that was previously installed can no longer be found or that some subsidiary component of a service provider (such as a VxD) cannot be found. When this error is encountered, the application should advise the user to correct the problem with the Driver Setup function within the Telephony Control Panel.

  • Although each application needs only one associated with TAPI, it can call an initialization function more than once to specify other message notification path.
  • Both lineInitializeEx and lineShutdown (and the corresponding phone functions) operate synchronously. These functions return a success or failure indication, not an asynchronous request identifier.

Upon completion, the lineInitializeEx function returns two pieces of information to the application: an application handle and the number of available line devices.

  • The application handle represents the application's usage of TAPI. That is, to TAPI, it represents the application. TAPI functions that use line or call handles (explained later in this section) do not require the application handle, because this handle is derived from the specified line, phone, or call handle.
  • The lineInitializeEx function also returns the number of line devices available to the application through TAPI. Line devices are identified by their device identifier (device identifier). Valid device identifiers range from zero to one less than the number of line devices. For example, if lineInitializeEx reports that there are two line devices in a system, the valid line device identifiers are 0 and 1.

After an application is finished calling TAPI's line functions, it calls lineShutdown and passes its application handle to terminate its usage of TAPI. This allows TAPI to free any resources assigned to the application.


Calls

Unlike line devices and addresses, calls are dynamic. A call represents a connection between two (or more) addresses. The originating address (the caller) is the address from which the call originates, and the destination address (the called) identifies the remote end point or station with which the originator wishes to communicate.

Zero, one, or more calls can exist on a single address at any given time. A familiar example of multiple calls on a single address is call waiting. During a conversation with one party, a subscriber with call waiting is alerted that another party is trying to call. The subscriber can flash the phone to answer the second caller (which automatically places the first party on hold) and then toggle between the two parties by flashing. In this example, the subscriber has two calls on one address on the line. Because the person at the telephone handset can be talking to only one remote party at a time, only one call is active per line at any point in time. The telephone switch keeps the other calls on hold. With a line able to encompass more than one channel, different configurations can allow multiple active calls on a line at the same time.


Call Handles

TAPI identifies a specific call by means of the call's handle, and TAPI assigns call handles as required. One call handle exists for every call owned or monitored by an application, and an application can obtain call handles in a number of well defined ways. Certain TAPI functions create new calls. As they do so, they return any new call's handle to the application. Sometimes, call handles are provided unsolicited in message sent to the application from TAPI, as is the case with incoming calls or calls being handed off by other applications.

For every call, one handle exists per application—unique call handles are provided to each application by TAPI. This means that different applications with handles to the same call use different handles for it, which limits the scope of a call handle to a single application. In addition, the service provider can assign a unique call ID to a call (unrelated to the call's handle), which is used to track the call across transfers. Whether or not a service provider can assign call IDs to calls is a device capability.

The privileges of an application for a given call are maintained by TAPI and are not the property of an application's handle for the call. (For information about call privileges, see TAPI Applications.) Resources such as memory are allocated dynamically for each call for each application that is given a handle to the call. These resources are not automatically deallocated when the call is dropped as the application may still find it useful to extract information from the call (such as for logging purposes). Therefore, applications must dispose of their call handle when they have finished using it by calling the lineDeallocateCall function.


Version Negotiation

Over time, different versions may exist for TAPI, applications, and service providers for a line or phone. New versions may define new features, new fields to data structures, and so on. Version numbers therefore indicate how to interpret various data structures.

To allow optimal interoperability of different versions of applications, versions of TAPI itself, and versions of service providers by different vendors, TAPI provides a simple, two-step version negotiation mechanism for applications. Two different versions must be agreed on by the application, TAPI, and the service provider for each line device. The first is the version number for Basic and Supplementary Telephony and is referred to as the API version. The other is for provider-specific extensions, if any, and is referred to as the extension version. The format of the data structures and datatypes used by TAPI's basic and supplementary features is defined by the API version, while the extension version determines the format of the data structures defined by the vendor-specific extensions.

Version negotiation proceeds in two phases. In the first phase, the API version number is negotiated and the extension identifier associated with any vendor-specific extensions supported on the device is obtained. In the second phase, the extension version is negotiated. If the application does not use any API extensions, it skips the second phase and extensions are not activated by the service provider. If the application does want to use extensions, but the service provider's extensions (the extension identifier) are not recognized by the application, the application should skip the negotiation for extension version as well. Each vendor has its own set of legal (recognized) versions for each set of extension specifications it distributes.

The lineNegotiateAPIVersion function is used to negotiate the API version number to use. It also retrieves the extension identifier supported by the line device, returning zeros if no extensions are supported. With this function call, the application provides the API version range it is compatible with. TAPI in turn negotiates with the line's service provider to determine which API version range it supports. TAPI next selects a version number (typically, although not necessarily, the highest version number) in the overlapping version range that the application, the DLL, and the service provider have supplied. This number is returned to the application, along with the extension identifier that defines the extensions available from that line's service provider.

If the application wants to use the extensions defined by the returned extension identifier, it must first call lineNegotiateExtVersion to negotiate the extension version. In a similar negotiation phase, the application specifies the already agreed-upon API version and the extension version range it supports. TAPI passes this information to the service provider for the line. The service provider checks the API version and the extension version range against its own, and selects the appropriate extension version number, if one exists.

When the application later calls lineGetDevCaps, it returns a set of device capabilities for the line that correspond to the results of version negotiation. These include the line's device capabilities consistent with the API version and the line's device-specific capabilities consistent with the extension version. The application must specify both of these version numbers when it opens a line. At that point, the application, the DLL, and the service provider are committed to using the agreed-upon versions. If device-specific extensions are not to be used, the extension version should be specified as zero.

In an environment where multiple applications open the same line device, the first application to open the line device selects the versions for all future applications that want to use the line (service providers do not support multiple versions simultaneously.) Similarly, an application that opens multiple line devices may find it easier to operate all line devices under the same API version number.


Phone Devices Overview

A phone device is one of the two device classes supported by TAPI. This section describes phone devices and explains how to use the TAPI phone functions to access these devices.


The Phone Device

A phone device is a device that supports the phone device class and that includes some or all of the following elements:

  • Hookswitch/transducer This is a means for audio input and output. TAPI recognizes that a phone device can have several transducers, which can be activated and deactivated (taken offhook or placed onhook) under application or manual user control. TAPI identifies three types of hookswitch devices common to many phone sets:

    Handset The traditional mouth-and-ear piece combination that must be manually lifted from a cradle and held against the user's ear.

    Speakerphone Enables the user to conduct calls hands-free. The hookswitch state of a speakerphone can usually be changed both manually and by the API. The speakerphone can be internal or external to the phone device. The speaker part of a speakerphone allows multiple listeners.

    Headset Enables the user to conduct calls hands-free. The hookswitch state of a headset can usually be changed both manually and by the API.

    A hookswitch must be offhook to allow audio data to be sent to and/or received by the corresponding transducer.

  • Volume Control/Gain Control/Mute Each hookswitch device is the pairing of a speaker and a microphone component. The API provides for volume control and muting of speaker components and for gain control or muting of microphone components.
  • Ringer A means for alerting users, usually through a bell. A phone device may be able to ring in a variety of modes or patterns.
  • Display A mechanism for visually presenting messages to the user. A phone display is characterized by its number of rows and columns.
  • Phone buttons An array of buttons. Whenever the user presses a button on the phone set, the API reports that the corresponding button was pressed. Button-lamp identifiers identify a button and lamp pair. Of course, it is possible to have button-lamp pairs with either no button or no lamp. Button-lamp identifiers are integer values that range from 0 to the maximum number of button-lamps available on the phone device, minus one. Each button belongs to a button class. Classes include call appearance buttons, feature buttons, keypad buttons, and local buttons.
  • Lamps An array of lamps (such as LEDs) individually controllable from the API. Lamps can be lit in different modes by varying the on and off frequency. The button-lamp identifier identifies the lamp.
  • Data areas Memory areas in the phone device where instruction code or data can be downloaded to and/or uploaded from. The downloaded information would affect the behavior (or in other words, program) the phone device.

TAPI allows an application to monitor and control elements of the phone device. The most useful elements for an application are the hookswitch devices. The phone set can act as an audio I/O device (to the computer) with volume control, gain control and mute, a ringer (for alerting the user), data areas (for programming the phone), and perhaps a display, though the computer's display is more capable. The application writer is discouraged from directly controlling or using phone lamps or phone buttons, because lamp and button capabilities can vary widely among phone sets, and applications can quickly become tailored to specific phone sets.

There is no guaranteed core set of services supported by all phone devices as there is for line devices (the Basic Telephony Services). Therefore, before an application can use a phone device, the application must first determine the exact capabilities of the phone device. Telephony capability varies with the configuration (client versus client/server), the telephone hardware, and the service-provider software. Applications should make no assumptions as to what telephony capabilities are available. An application determines the device capabilities of a phone device by calling the phoneGetDevCaps function. A phone's device capabilities indicate which of these elements exist for each phone device present in the system and what their capabilities are. Although strongly oriented toward real-life telephone sets, this abstraction can provide a meaningful implementation (or subset thereof) for other devices as well. Take as an example a separate headset directly connected and controllable from the computer and operated as a phone device. Hookswitch changes can be triggered by detection of voice energy (offhook) or a period of silence (onhook); ringing can be emulated by the generation of an audible signal into the headset; a display can be emulated through text-to-speech conversion.

A phone device need not be realized in hardware, but can instead be emulated in software using a mouse- or keyboard-driven graphical command interface and the computer's speaker or sound system. Such a "soft phone" can be an application that uses TAPI. It can also be a service provider, which can be listed as a phone device available to other applications through the API, and as such is assigned a phone device identifier.

Depending on the environment and configuration, phone sets can be shared devices between the application and the switch. Some minor provision is made in the API where the switch can temporarily suspend the API's control of a phone device.


Initialization and Shutdown

For an application to use any of TAPI's 30 supplementary phone functions, it needs a connection to TAPI, through which it can receive messages. The application establishes this connection using the phoneInitializeEx function. In this function, the application specifies the notification mechanism by which TAPI informs the application of changes in the state of the phone and of asynchronous completion of phone functions.

The phoneInitializeEx function returns two pieces of information to the application: an application handle, and the number of phone devices. The application handle represents the application's usage of TAPI. The TAPI functions that use phone handles do not require the application handle, as this handle is derived from the specified phone handle.

The second piece of information returned by phoneInitializeEx is the number of phone devices available to TAPI. Phone devices are identified by their device identifier (device ID). Valid device identifiers range from zero to the number of phone devices minus one. For example, if phoneInitializeEx reports that there are two phone devices in a system, then valid phone device identifiers are 0 and 1. After an application is finished using the phone functions of TAPI, it invokes phoneShutdown, passing its application handle to shut down its usage of TAPI. This allows TAPI to free any resources assigned to the application.

Both phoneInitializeEx and phoneShutdown operate synchronously. That is, these functions either return a success or failure indication, and never return an asynchronous request identifier.


Opening and Closing Phone Devices

After determining the capabilities of a phone device, an application must open the device before it can access functions on that phone. After a phone device has been successfully opened, the application is returned a handle representing the open phone. A phone device can be opened in different modes, thus providing a structured way of sharing a phone device.

The phoneOpen function opens the specified phone device to give the application access to functions on the phone. A phone device is identified to phoneOpen by means of its device identifier, which is passed as the dwDeviceID parameter.


Operating Modes and Privileges

The application can request one of two operating modes when opening a phone device. These modes reflect the privileges the application requests for the device:

  • Opening a phone for monitor privileges lets the application determine the status of the phone device. Messages are sent to the application when status changes on the phone device are detected.
  • An application that opens a phone device for owner privileges can use operations that modify the state of the phone device. Owner privilege automatically includes full monitor privileges as well. At any time, a given phone device can be open only once for owner privileges, but multiple times for monitor privileges. All phoneSet operations require owner privileges, while all phoneGet operations require only monitor privileges.


Device IDs

Other TAPI phone functions use a handle to an open phone device to identify the open phone device. The only functions for phone devices that take a phone device identifier parameter (as opposed to a phone handle) are the phoneGetDevCaps and phoneOpen functions. An application can retrieve the phone's device identifier by using the phoneGetID function with the phone handle as a parameter.

An application can also obtain device identifiers for various device classes associated with an opened phone by invoking phoneGetID. See TAPI Device Classes for device class names.

This function takes a phone handle and a device class description. It returns the device identifier for the device of the given device class that is associated with the open phone device. If the device class is "tapi/phone", the device identifier of the phone device is returned.

In contrast with line devices, for which the basic line services provide the equivalent of POTS, no minimum guaranteed set of functions is defined for phone devices. While each phone device provides at least the functions and messages described in this section, they do not offer any actual operations on the physical phone device.


Closing the Phone Device

The phoneClose function closes the specified phone device. The phone device can also be forcibly closed after the user has modified the configuration of that phone or its driver. If the user wants the configuration changes to be effective immediately (as opposed to after the next system restart), and they affect the application's current view of the device (such as a change in device capabilities), then a service provider can forcibly close the phone device.

These messages can also be sent unsolicited as a result of the phone device being reclaimed in some other manner. An application should therefore be prepared to handle unsolicited PHONE_CLOSE messages. At the time the phone device is closed, any outstanding asynchronous replies pertaining to that device are suppressed.


Hookswitch Devices

A phone device can have multiple hookswitch devices. A hookswitch is the switch that connects or disconnects a device from the phone line. On a telephone, for example, this is the switch that is automatically activated when a user lifts the receiver from the cradle to get a new dial tone. TAPI defines three types of hookswitch devices for a phone: handset, speakerphone, and headset. Each hookswitch device has a speaker and a microphone component, and operates in one of four hookswitch modes:

  • Onhook The hookswitch device is onhook, and both its microphone and speaker are disabled.
  • Microphone only The hookswitch device is offhook, its microphone is enabled, and its speaker is mute.
  • Speaker only The hookswitch device is offhook, its microphone is mute, and its speaker is enabled.
  • Microphone and speaker The hookswitch device is offhook, and both microphone and speaker are enabled.

The phoneSetHookSwitch function is used to set the hookswitch mode of one or more of the hookswitch devices of an open phone device. For example, to mute or unmute the microphone or speaker component of a hookswitch device, use phoneSetHookSwitch with the appropriate hookswitch mode. The phoneGetHookSwitch function can be used to query the hookswitch mode of a hookswitch device of an open phone device.

When the mode of a phone's hookswitch device is changed manually, for example by lifting the handset from its cradle, a PHONE_STATE message is sent to the application to notify the application about the state change. Parameters to this message provide an indication of the change.

The volume of the speaker component of a hookswitch device can be set with phoneSetVolume. Volume setting is different from mute in that muting a speaker and later unmuting it will preserve the volume setting of the speaker. The phoneGetVolume function can be used to return the current volume setting of a hookswitch device's speaker of an open phone device.

The microphone component of a hookswitch device can also be gain controlled. Gain setting is different from mute in that muting a microphone and later unmuting it will preserve the gain setting of the microphone. Use phoneSetGain to set the gain of a hookswitch device's microphone of an open phone device, and phoneGetGain to return the gain setting of a hookswitch device's microphone of an opened phone.

When the volume or gain of a phone's hookswitch device is changed, a PHONE_STATE message is sent to the application function to notify the application about the state change. Parameters to this message provide an indication of the change.


Display

TAPI provides access to a phone's display. The display is modeled as an alphanumeric area with rows and columns. A phone's device capabilities indicate the size of a phone's display as the number of rows and the number of columns. Both these numbers are zero if the phone device does not have a display. Use phoneSetDisplay to write information to the display of an open phone device, and phoneGetDisplay to retrieve the current contents of a phone's display.

When the display of a phone device is changed, a PHONE_STATE message is sent to the application function to notify the application about the state change. Parameters to this message provide an indication of the change.


Ring

A single phone may be able to ring with different ring modes. Given the wide variety of ring modes available, ring modes are identified by means of their ring mode number. A ring mode number ranges from zero to the number of available ring modes minus one.

The functions an application would use to control a phone device's ring modes are phoneSetRing, which rings an open phone device according to a given ring mode, and phoneGetRing, which returns the current ring mode of an opened phone device.

When the ring mode of a phone device is changed, a PHONE_STATE message is sent to the application to notify the application about the state change. Parameters to this message provide an indication of the change.


Phone Buttons

TAPI models a phone's buttons and lamps as button-lamp pairs. A button with no lamp next to it or a lamp with no button is specified using a "dummy" indicator for the missing lamp or button. A button with multiple lamps is modeled by using multiple button-lamp pairs.

Information associated with a phone button can be set and retrieved. When a button is pressed, a PHONE_BUTTON message is sent to the application function. The parameters of this message are a handle to the phone device and the button-lamp identifier of the button that was pressed. The keypad buttons '0' through '9', '*', and '#' are assigned the fixed button-lamp identifiers 0 through 11.

The functions associated with buttons are phoneSetButtonInfo, which sets the information associated with a button on a phone device, and phoneGetButtonInfo, which returns information associated with a button on a phone device. The PHONE_BUTTON message is sent to an application when a button on the phone is pressed.

The information associated with a button does not carry any semantic meaning as far as TAPI is concerned. It is useful for device-specific applications that understand the meaning of this information for a given phone device, or for display to the user, such as online help.


Lamps

The lamps on a phone device can be lit in a variety of different lighting modes. Unlike ringing patterns, lamp modes are more uniform across phone sets of different vendors. A common set of lamp modes is defined by the API. A lamp identified by its lamp-button identifier can be lit in a given lamp mode. A lamp can also be queried for its current lamp mode.

The TAPI functions used for lamps are phoneSetLamp, which lights a lamp on a specified open phone device in a given lamp lighting mode, and phoneGetLamp, which returns the current lamp mode of the specified lamp.

When a lamp of a phone device is changed, a PHONE_STATE message is sent to the application to notify the application about the state change. Parameters to this message provide an indication of the change.


Data Areas

Some phone sets support the notion of downloading data from or uploading data to the phone device, which allows the phone set to be programmed in a variety of ways. TAPI models these phone sets as having one or more download or upload areas. Each area is identified by a number that ranges from zero to the number of data areas available on the phone minus one. Sizes of each area can vary. The format of the data itself is device-specific.

The TAPI phoneSetData function downloads a buffer of data to a given data area in the phone device, and the phoneGetData function uploads the contents of a given data area in the phone device to a buffer.

When a data area of a phone device is changed, a PHONE_STATE message is sent to the application to notify the application about the state change. Parameters to this message provide an indication of the change.


Status

Most of the get and set operations deal with one component of information only. The phoneGetStatus function returns complete status information about a phone device to an application.

As mentioned earlier, whenever a status item changes on the phone device, a PHONE_STATE message is sent to the application function. This message's parameters include a handle to the phone device and an indication of the status item that changed.

An application can use phoneSetStatusMessages to select the specific status changes for which it wants to be notified. Correspondingly, phoneGetStatusMessages returns the status changes for which the application wants to be notified.


Extended Telephony Phone Functions

The Extended Phone Services (or Device-Specific Phone Services) include all extensions to the TAPI defined by the service provider. TAPI defines a mechanism that enables service-provider vendors to extend TAPI using device-specific extensions. TAPI defines only the extension mechanism, and by doing so provides access to device-specific extensions. TAPI does not define their behavior, which is completely defined by the service provider.

TAPI consists of scalar and bit-flag data constant definitions, data structures, functions, and messages. Procedures are defined that enable a vendor to extend most of these, as described in the following topics.


Scalar Data Constants

For extensible scalar data constants, a service-provider vendor can define new values in a specified range. Because most data constants are DWORDs, the range 0x00000000 through 0x7FFFFFFF is typically reserved for common future extensions, while 0x80000000 through 0xFFFFFFFF is available for vendor-specific extensions. The assumption is that a vendor would define values that are natural extensions of the datatypes defined by the API.


Bit-Flag Data Constants

For extensible bit-flag data constants, a service-provider vendor can define new values for specified bits. Because most bit-flag constants are DWORDs, a specific number of the lower bits are usually reserved for common extensions, while the remaining upper bits are available for vendor-specific extensions. Common bit flags are assigned from bit zero up, and vendor-specific extensions should be assigned from bit 31 down. This scheme provides maximum flexibility in assigning bit positions to common extensions, as opposed to vendor-specific extensions. A vendor is expected to define new values that are natural extensions of the bit flags defined by the API.

Extensible data structures have a variably sized field that is reserved for device-specific use. Because the field is variably sized, the service provider decides the field's amount of information and interpretation. A vendor that defines a device-specific field is expected to make these natural extensions of the original data structure defined by the API.


Functions and Messages

The phoneDevSpecific function and its associated PHONE_DEVSPECIFIC message enable an application to access device-specific phone features that are unavailable through the common telephony services for phones. In other words, phoneDevSpecific is the device-specific escape function that allows vendor-dependent extensions, and PHONE_DEVSPECIFIC is the device-specific message that is sent to the application.

The parameter profile of the phoneDevSpecific function is generic in that little interpretation of the parameters is made by TAPI. Rather, the interpretation of the parameters is defined by the service provider and must be understood by an application that uses them. The parameters are simply passed through by TAPI from the application to the service provider. An application that relies on device-specific extensions will usually not work with other service providers, but applications written to the common telephony phone services will work with the extended service provider.


Assisted Telephony Overview

Assisted telephony provides very basic telephony functionality to primarily non-telephonic applications. If your application needs extensive telephonic control or is meant to handle incoming calls, you can skip this section.


Call Requests

Assisted Telephony provides telephony-enabled applications with an easy-to-use mechanism for making phone calls without requiring the developer to become fully literate in telephony.

The tapiRequestMakeCall function requests a voice call between the user and a remote party specified by its phone number. The request is made to TAPI, which passes it to an application that is registered as a recipient of such requests. This recipient is a call manager application.

After the application has made the request, the call is controlled entirely from the call manager application because Assisted Telephony applications cannot manage calls. Because the more complex aspects of telephony and all user-interface operations are handled by the call manager application, telephony-enabled applications need not be modified in any substantial way. In fact, applications that allow this operation to be invoked from their built-in script language may not need to be modified at all.

The tapiGetLocationInfo function returns to the application the country code and city (area) code which the user has set in the current location parameters in the Telephony Control Panel. The application can use this information to assist the user in forming proper canonical telephone numbers, such as by offering these as defaults when new numbers are entered in a phone book entry or database record.


Request Recipients

Two kinds of applications are needed to run Assisted Telephony. Assisted Telephony clients are applications that use Assisted Telephony by calling the functions that have the prefix "tapi." An example of such a client application would be a spreadsheet to which a Dial menu command or toolbar button is added.

Assisted Telephony servers are applications that can execute Telephony API functions that result from another application's call to a "tapi"-prefixed function. To make itself known as an Assisted Telephony server, such an application registers as one using the lineRegisterRequestRecipient function.

The functions of Assisted Telephony (which begin with the prefix "tapi") are known as request functions. Assisted Telephony applications that process these requests—Assisted Telephony servers—are called request recipients.


Assisted Telephony Requests

Applications that use Assisted Telephony services only initiate requests that are temporarily queued by TAPI. It is the request recipient application that retrieves these requests and executes them on behalf of the Assisted Telephony application. The tapiRequestMakeCall function requests the establishment of a voice call. The requesting application does not control the call.

TAPI allows the user to establish different or the same request recipient applications for each of these services. An application becomes a request recipient by registering with lineRegisterRequestRecipient, in which TRUE is specified as the value for the parameter bEnable. (Specifying FALSE deregisters the application as a request recipient, which it should do when it has determined that its recipient duties are through for the current session.) The application selects the services it wants to handle in the dwRequestMode parameter of lineRegisterRequestRecipient. A possible value for a request is LINEREQUESTMODE_MAKECALL, to show that the application will handle tapiRequestMakeCall requests. If multiple applications register for the same services, a priority scheme is used to allow the user to select which application is preferred for handling requests. This priority scheme is identical to that used for call hand-off and the routing of incoming calls based on a list of filenames in HandoffPriorities in the registry.


Processing Assisted Telephony Requests

The process with which requests are delivered and serviced is as follows:

  1. When TAPI receives an Assisted Telephony request, it checks for a request recipient, that is, an application currently registered to process that type of request. If there is a request recipient, the request is queued, and the highest-priority application that has registered for that request's service is sent a LINE_REQUEST message. The message notifies the request recipient that a new request has arrived, and it carries an indication of the request's mode.
  2. If TAPI cannot find a currently running application to process such a request, it tries to launch an application that has been registered as capable of doing so. This registration information is recorded in HandoffPriorities in the registry. TAPI tries to launch applications in the order in which they are listed in the HandoffPriorities section. (See the following step.)

    If no application is currently registered, TAPI examines the list of request-processing applications on the associated entry in HandoffPriorities. If the associated line is missing from the file, if there are no applications listed on it, or if none of the applications in the list can be launched, the request is rejected with the error TAPIERR_NOREQUESTRECIPIENT.

    When a request recipient is launched (whether or not it has been launched by TAPI) it is its duty to call lineRegisterRequestRecipient during the startup process and register itself as a request recipient.

  3. If one or more applications are listed in the entry, TAPI begins with the first listed application (highest priority), and attempts to launch it using the CreateProcess function. If the attempt to launch the application fails, TAPI attempts to launch the next application in the list. When any application launches successfully, TAPI simply queues the request and returns a success indication to the application even though the request hasn't yet been signaled to the request recipient.

    After the request recipient application is launched, it calls lineRegisterRequestRecipient, which causes a LINE_REQUEST message to be sent, signaling that the request is queued. If for some reason the launched application never registers, the request remains queued and remains in the queue indefinitely until an application registers for that type of request.

  4. If TAPI finds such a registered application already running or successfully launches one, it queues the request, sending a LINE_REQUEST message to the server application, and returns a success indication for the function call to the Assisted Telephony application. This success message states only that the request has been accepted and queued, not that it has been successfully executed.

When the server application is ready to process a request, it calls the lineGetRequest function. This lets it receive any information it needs, such as an address to dial. It then processes the request, using the TAPI functions (such as lineMakeCall and lineDrop) that would otherwise be used to place the call. Invoking lineGetRequest removes the request from TAPI, and the request parameters are copied in an application-allocated request buffer. The size and interpretation of the contents of the buffer depend on the request mode.

The server must ensure that it uses the correct parameters when executing requests. When doing so, these steps are followed:

  1. The request recipient first receives a LINE_REQUEST message informing it that requests can exist for it in the request queue. This tells the application to call lineGetRequest and keep calling it until the queue is drained (if the request is for making a new call), or to drop an existing call. This message does not contain the parameters for the request, except in the case of a request to drop an existing call.
  2. If the request is to make a new call, the Assisted Telephony server uses the lineGetRequest function to retrieve the full request, which includes the request's parameters. The server now has all the information it needs, such as the number to dial or the identification of the maker of the request. First, however, the server must allocate the memory needed to store this information.
  3. Finally, the server executes the request by invoking the appropriate TAPI function or set of functions.

If TAPI cannot launch an application capable of serving as a request recipient, the Assisted Telephony call fails and returns the error TAPIERR_NOREQUESTRECIPIENT.


Notes on Request Recipient Operations

The following information concerns systems on which Assisted Telephony requests are processed:

  • The default registry should list a call manager application in the priority list for tapiRequestMakeCall. It would be helpful, but not essential, for the call manager application to have a menu option that allows users to set it to the highest priority.
  • When an Assisted Telephony recipient application is launched automatically by TAPI and if it is the only TAPI application in the system, this action initializes TAPI. If the Assisted Telephony recipient application initializes and shuts down the line device before registering for Assisted Telephony requests, TAPI is shut down as well, and the Assisted Telephony request is lost. Assisted Telephony requests might also be lost when another TAPI application that is launched performs an initialize and shutdown.


Using Assisted Telephony

You might use assisted telephony in a word-processing application. Consider a word-processing application that has a button with a caption of "George." When the user selects a telephone number in a document and clicks this button, the application sends a request (tapiRequestMakeCall) to the call-control application, which dials the number and notifies the user of the call's status.


Data Structures Overview

This section discusses the following topics on how to use line device structures and phone device structures.

Memory Allocation

Variably Sized Data Structures

Extensibility


Memory Allocation

Memory for all data structures used by TAPI must be allocated by the application. The application passes a pointer to the API function that returns the information, and the function fills the data structure with the requested information. If the operation is asynchronous, then the information is not available until the asynchronous reply message indicates success.

All data structures used to pass information between the application and the TAPI are flattened. This means that data structures do not contain pointers to substructures that contain variably sized components of information. Instead, data structures that are used to pass variable amounts of information back to the application have the following meta structure:

DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;
      <fixed size fields>
    DWORD  dw<VarSizeField1>Size;
    DWORD  dw<VarSizeField1>Offset;
      <fixed size fields>
    DWORD  dw<VarSizeField2>Size;
    DWORD  dw<VarSizeField2>Offset;
      <common extensions>
      <var sized field1>
      <var sized field2>

The dwTotalSize member is the size in bytes allocated to this data structure. It marks the end of the data structure and is set by the application before it invokes the function that uses this data structure. The function does not read or write beyond this size. An application must set the dwTotalSize member to indicate the total number of bytes allocated for TAPI to return the contents of the structure.

The dwNeededSize member is filled in by TAPI. It indicates how many bytes are needed to return all the information requested. The existence of variably sized fields often makes it impossible for the application to estimate the data structure size it needs to allocate. This field simply returns the number of bytes actually needed for the information. This number could be smaller than, equal to, or larger than dwTotalSize, and it includes space for the dwTotalSize member itself. If larger, the returned structure is only partially filled. If the fields the application is interested in are available in the partial structure, nothing else must be done. Otherwise, the application should allocate a structure at least the size of dwNeededSize and invoke the function again. Usually, enough space is available this time to return all the information, although it is possible the size could have increased again.

The dwUsedSize member is filled in by TAPI if it returns information to the application to indicate the actual size in bytes of the portion of the data structure that contains useful information. If, for example, a structure that was allocated was too small and the truncated field is a variably sized field, dwNeededSize is larger than dwTotalSize, and the truncated field is left empty. The dwUsedSize member could therefore be smaller than dwTotalSize. Partial field values are not returned.

Following this header is the fixed part of the data structure. It contains regular fields and size/offset pairs that describe the actual variably sized fields. The offset field contains the offset in bytes of the variably sized field from the beginning of the record. The size field contains the size in bytes of the variably sized field. If a variably sized field is empty, then the size field is zero and the offset is set to zero. Variably sized fields that would be truncated if the total structure size is insufficient are left empty. That is, their size field is set to zero and the offset is set to zero. The variably sized fields follow the fixed fields.


Variably Sized Data Structures

When variably sized data structures are used to transmit information between TAPI and the application, the application is responsible for allocating the necessary memory. The amount of memory allocated must be at least large enough for the fixed portion of the data structure, and is set by the application in the dwTotalSize member of the data structure. The dwUsedSize and dwNeededSize members are filled in by TAPI. If dwTotalSize is less than the size of the fixed portion, then LINEERR/ PHONEERR_STRUCTURETOOSMALL is returned. If a function returns success, then all the fields in the fixed portion have been filled in. The dwUsedSize and dwNeededSize members can be compared to determine if all variable parts have been filled in, and how much space would be required to fill them all in.

If dwNeededSize is equal to dwUsedSize, then all fixed and variable parts have been filled in. If dwNeededSize is larger than dwUsedSize, some variable parts may have been filled in, but exactly which variably sized fields have been filled in is undefined. No variable part is ever truncated, and variable parts that would have been truncated due to insufficient space are indicated by having both of their corresponding "Offset" and "Size" parts set to zero. If these are not both zero (and no error was returned), they indicate the offset and size of valid, nontruncated variable-part data.

An application can always guarantee that all variable parts are filled in by allocating and indicating dwNeededSize bytes for the structure and calling the "Get" function again until the function returns success and dwNeededSize equals dwUsedSize. This should happen on the second try except for race conditions that cause changes in the size of variable parts between calls, which should be a rare occurrence.

Note All ASCII, DBCS, and Unicode strings that occur in variably sized structures should be NULL-terminated according to normal C string handling conventions.


Extensibility

Provisions are made for extending constants and structures both in a device-independent way and in a device-specific (vendor-specific) way. In constants that are scalar enumerations, a range of values is reserved for future common extensions. The remainder of values are identified as device specific. A vendor can define meanings for these values in any way desired. Their interpretation is keyed to the extension identifier provided in the LINEDEVCAPS data structure. For constants that are defined as bit flags, a range of low-order bits are reserved, where the high-order bits can be extension specific. It is recommended that extended values and bit arrays use bits from the highest value or high-order bit down. This leaves the option to move the border between the common portion and extension portion if there is a need to do so in the future. Extensions to data structures are assigned a variably sized field with size/offset being part of the fixed part. TAPI describes for each data structure what device-specific extensions are allowed.

In addition to recognizing a specific extension identifier, the application must negotiate the extension version number that the application and the service provider operate under. This is done in the second version negotiation phase of the lineGetDevCaps function.

An extension identifier is a globally unique identifier. There is no central registry for extension identifiers. Instead, they are generated locally by the manufacturer by a utility that is available with the toolkit. The number is made up of parts such as a unique LAN address, time of day, and random number, to guarantee global uniqueness. Globally Unique Identifiers are designed to be distinguishable from HP/DEC universally unique identifiers and are thus fully compatible with them.


TAPI Reference

This section describes the TAPI elements necessary for writing a telephony application, namely:

TAPI Quick Function Reference

TAPI Unicode Support

TAPI Functions

TAPI Structures

TAPI Messages

TAPI Constants

TAPI Device Classes


TAPI Quick Function Reference

Following is the quick function reference for TAPI functions categorized by the three levels of telephony services: Basic, Supplementary, and Extended. Also included in this section is the quick function reference for the related Assisted Telephony services. See the overviews for Assisted Telephony and Service Levels for expanded discussion.

Basic Telephony Services Reference discusses TAPI functions associated with POTS-level telephony tasks.

Supplementary Telephony Services Reference discusses TAPI functions with more advanced features such as hold and transfer.

Extended Telephony Services Reference discusses functions that enable the user to access service provider-specific functions not directly defined by TAPI.

Assisted Telephony Services Reference discusses functions designed to let any Microsoft® Win32®-based application establish voice calls and media calls, such as in using a phone dialer.


Basic Telephony Services Reference

The Basic Telephony functions are listed by category in the following tables. A function is identified as asynchronous if it indicates completion in a REPLY message to the application. If the function always returns its result to the application immediately, the function is considered synchronous.

TAPI Initialization and Shutdown

lineInitializeEx | Initializes the TAPI line abstraction for use by the invoking application. Synchronous.
lineShutdown | Shuts down the application's use of TAPI's line abstraction. Synchronous.

Line Version Negotiation

lineNegotiateAPIVersion Allows an application to negotiate a TAPI version to use. Synchronous.

Line Status and Capabilities

lineGetDevCaps | Returns the capabilities of a given line device. Synchronous.
lineGetDevConfig | Returns configuration of a media stream device. Synchronous.
lineGetLineDevStatus | Returns current status of the specified open line device. Synchronous.
lineSetDevConfig | Sets the configuration of the specified media stream device. Synchronous.
lineSetStatusMessages | Specifies the status changes for which the application needs to be notified. Synchronous.
lineGetStatusMessages | Returns the application's current line and address status message settings. Synchronous.
lineGetID | Retrieves a device ID associated with the specified open line, address, or call. Synchronous.
lineGetIcon | Allows an application to retrieve an icon for display to the user. Synchronous.
lineConfigDialog | Causes the provider of the specified line device to display a dialog box that allows the user to configure parameters related to the line device. Synchronous.
lineConfigDialogEdit | Displays a dialog box allowing the user to change configuration information for a line device. Synchronous. Version 0x00010004.

Addresses

lineGetAddressCaps | Returns the telephony capabilities of an address. Synchronous.
lineGetAddressStatus | Returns current status of a specified address. Synchronous.
lineGetAddressID | Retrieves the address ID of an address specified using an alternate format. Synchronous.

Opening and Closing Line Devices

lineOpen | Opens a specified line device for providing subsequent monitoring and/or control of the line. Synchronous.
lineClose | Closes a specified opened line device. Synchronous.

Address Formats

lineTranslateAddress | Translates between an address in canonical format and an address in dialable format. Synchronous.
lineSetCurrentLocation | Sets the location used as the context for address translation. Synchronous.
lineSetTollList | Manipulates the toll list. Synchronous.
lineGetTranslateCaps | Returns address translation capabilities. Synchronous.

Call States and Events

lineGetCallInfo | Returns fixed information about a call. Synchronous.
lineGetCallStatus | Returns complete call status information for the specified call. Synchronous.
lineSetAppSpecific | Sets the application-specific field of a call's information structure. Synchronous.

Making Calls

lineMakeCall | Makes an outbound call and returns a call handle for it. Asynchronous.
lineDial | Dials (parts of one or more) dialable addresses. Asynchronous.

Answering Incoming Calls

lineAnswer Answers an incoming call. Asynchronous.

Toll Saver Support

lineSetNumRings | Indicates the number of rings after which incoming calls are to be answered. Synchronous.
lineGetNumRings | Returns the minimum number of rings requested with lineSetNumRings. Synchronous.

Call Privilege Control

lineSetCallPrivilege Sets the application's privilege to the privilege specified. Synchronous.

Call Drop Functions

lineDrop | Disconnects a call, or abandons a call attempt in progress. Asynchronous.
lineDeallocateCall | Deallocates the specified call handle. Synchronous.

Call Handle Manipulation

lineHandoff | Hands off call ownership and/or changes an application's privileges to a call. Synchronous.
lineGetNewCalls | Returns call handles to calls on a specified line or address for which the application does not yet have handles. Synchronous.
lineGetConfRelatedCalls | Returns a list of call handles that are part of the same conference call as the call specified as a parameter. Synchronous.

Location and Country Information

lineTranslateDialog | Displays a dialog box allowing the user to change location and calling card information. Synchronous. Version 0x00010004.
lineGetCountry | Retrieves dialing rules and other information about a given country. Synchronous. Version 0x00010004.

Request Recipient Services

The following two functions are used only in support of Assisted Telephony.

lineRegisterRequestRecipient | Registers or deregisters the application as a request recipient for the specified request mode. Synchronous.
lineGetRequest | Gets the next request from the Telephony dynamic link library. Synchronous.


Supplementary Telephony Services Reference

The Supplementary Telephony functions are listed by category in the following topics.

Supplementary Line Services Functions

Supplementary Phone Services Functions


Supplementary Line Services Functions

Supplementary Line Service Functions

The supplementary line service functions are listed by category in the following topics. A function is identified as asynchronous if it will indicate completion in a REPLY message to the application. If the function always returns its result to the application immediately, the function is considered synchronous.

Bearer Mode and Rate

lineSetCallParams Requests a change in the call parameters of an existing call. Synchronous.

Media Monitoring

lineMonitorMedia Enables or disables media mode notification on a specified call. Synchronous.

Digit Monitoring and Gathering

lineMonitorDigits | Enables or disables digit detection notification on a specified call. Synchronous.
lineGatherDigits | Performs the buffered gathering of digits on a call. Synchronous.

Tone Monitoring

lineMonitorTones Specifies which tones to detect on a specified call. Synchronous.

Media Control

lineSetMediaControl | Sets up a call's media stream for media control. Synchronous.
lineSetMediaMode | Sets the media mode(s) of the specified call in its LINECALLINFO structure. Synchronous.

Generating Inband Digits and Tones

lineGenerateDigits | Generates inband digits on a call. Synchronous.
lineGenerateTone | Generates a given set of tones inband on a call. Synchronous.

Call Accept and Redirect

lineAccept | Accepts an offered call and starts alerting both caller (ringback) and called party (ring). Asynchronous.
lineRedirect | Redirects an offering call to another address. Asynchronous.

Call Reject

lineDrop Disconnects a call, or abandons a call attempt in progress. Asynchronous.

Call Hold

lineHold | Places the specified call on hard hold. Asynchronous.
lineUnhold | Retrieves a held call. Asynchronous.

Making Calls

lineSecureCall Secures an existing call from interference by other events such as call-waiting beeps on data connections. Asynchronous.

Call Transfer

lineSetupTransfer | Prepares a specified call for transfer to another address. Asynchronous.
lineCompleteTransfer | Transfers a call that was set up for transfer to another call, or enters a three-way conference. Asynchronous.
lineBlindTransfer | Transfers a call to another party. Asynchronous.
lineSwapHold | Swaps the active call with the call currently on consultation hold. Asynchronous.

Call Conference

lineSetupConference | Prepares a given call for the addition of another party. Asynchronous.
linePrepareAddToConference | Prepares to add a party to an existing conference call by placing the conference call in a hold state and creating a consultation call that can be added later to the conference call. Asynchronous.
lineAddToConference | Adds a consultation call to an existing conference call. Asynchronous.
lineRemoveFromConference | Removes a party from a conference call. Asynchronous.

Call Park

linePark | Parks a given call at another address. Asynchronous.
lineUnpark | Retrieves a parked call. Asynchronous.

Call Forwarding

lineForward Sets or cancels call forwarding requests. Asynchronous.

Call Pickup

linePickup Picks up a call alerting at a specified destination address and returns a call handle for the picked-up call (linePickup can also be used for call waiting). Asynchronous.

Sending Information to Remote Party

lineReleaseUserUserInfo | Releases user-user information, permitting the system to overwrite this storage with new information. Asynchronous. Version 0x00010004.
lineSendUserUserInfo | Sends user-user information to the remote party on the specified call. Asynchronous.

Call Completion

lineCompleteCall | Places a call completion request. Asynchronous.
lineUncompleteCall | Cancels a call completion request. Asynchronous.

Setting a Terminal for Phone Conversations

lineSetTerminal Specifies the terminal device to which the specified line, address events, or call media stream events are routed. Asynchronous.

Application Priority

lineGetAppPriority | Retrieves handoff and/or Assisted Telephony priority information for an application. Synchronous. Version 0x00010004.
lineSetAppPriority | Sets the handoff and/or Assisted Telephony priority for an application. Synchronous. Version 0x00010004.

Service Provider Management

lineAddProvider | Installs a telephony service provider. Synchronous. Version 0x00010004.
lineConfigProvider | Displays configuration dialog box of a service provider. Synchronous. Version 0x00010004.
lineRemoveProvider | Removes an existing telephony service provider. Synchronous. Version 0x00010004.
lineGetProviderList | Retrieves a list of installed service providers. Synchronous. Version 0x00010004.

Agents

lineAgentSpecific | Allows the application to access proprietary handler-specific functions of the agent handler associated with the address. Asynchronous. Version 0x00020000.
lineGetAgentActivityList | Obtains the list of activities from which an application selects the functions an agent is performing. Asynchronous. Version 0x00020000.
lineGetAgentCaps | Obtains the agent-related capabilities supported on the specified line device. Asynchronous. Version 0x00020000.
lineGetAgentGroupList | Obtains the list of agent groups into which an agent can log into on the automatic call distributor. Asynchronous. Version 0x00020000.
lineGetAgentStatus | Obtains the agent-related status on the specified address. Asynchronous. Version 0x00020000.
lineSetAgentActivity | Sets the agent activity code associated with a particular address. Asynchronous. Version 0x00020000.
lineSetAgentGroup | Sets the agent groups that the agent is logged into on a particular address. Asynchronous. Version 0x00020000.
lineSetAgentState | Sets the agent state associated with a particular address. Asynchronous. Version 0x00020000.

Proxies

lineProxyMessage | Used by a registered proxy request handler to generate TAPI messages. Synchronous. Version 0x00020000.
lineProxyResponse | Indicates completion of a proxy request by a registered proxy handler. Synchronous. Version 0x00020000.

Quality of Service

lineSetCallQualityOfService Requests a change of the quality of service parameters for an existing call. Asynchronous. Version 0x00020000.

Miscellaneous

lineSetCallData | Sets the CallData member of the LINECALLINFO structure. Asynchronous. Version 0x00020000.
lineSetCallTreatment | Sets the sounds that the user hears when a call is unanswered or on hold. Asynchronous. Version 0x00020000. lineSetLineDevStatus
 | Sets the line device status. Asynchronous. Version 0x00020000.


Supplementary Phone Services Functions

The supplementary phone services functions are listed by category in the following topics. A function is identified as asynchronous if it will indicate completion in a REPLY message to the application. If the function always returns its result to the application immediately, the function is considered synchronous.

TAPI Initialization and Shutdown

phoneInitializeEx | Initializes TAPI phone abstraction for use by the invoking application. Synchronous.
phoneShutdown | Shuts down an application's use of TAPI's phone abstraction. Synchronous.

Phone Version Negotiation

phoneNegotiateAPIVersion Allows an application to negotiate a TAPI version to use. Synchronous.

Opening and Closing Phone Devices

phoneOpen | Opens the specified phone device, giving the application either owner or monitor privileges. Synchronous.
phoneClose | Closes a specified open phone device. Synchronous.

Phone Status and Capabilities

phoneGetDevCaps | Returns the capabilities of a given phone device. Synchronous.
phoneGetID | Returns a device ID for the given device class associated with the specified phone device. Synchronous.
phoneGetIcon | Allows an application to retrieve an icon for display to the user. Synchronous.
phoneConfigDialog | Causes the provider of the specified phone device to display a dialog box that allows the user to configure parameters related to the phone device. Synchronous.

Hookswitch Devices

phoneSetHookSwitch | Sets the hook state of an open phone's hookswitch devices to a specified mode. Asynchronous.
phoneGetHookSwitch | Queries the hookswitch mode of a hookswitch device of an open phone device. Synchronous.
phoneSetVolume | Sets the volume of a hookswitch device's speaker of an open phone device. Asynchronous.
phoneGetVolume | Returns the volume setting of a hookswitch device's speaker of an open phone device. Synchronous.
phoneSetGain | Sets the gain of a hookswitch device's mic of an open phone device. Asynchronous.
phoneGetGain | Returns the gain setting of a hookswitch device's mic of an open phone. Synchronous.

Display

phoneSetDisplay | Writes information to the display of an open phone device. Asynchronous.
phoneGetDisplay | Returns the current contents of a phone's display. Synchronous.

Ring

phoneSetRing | Rings an open phone device according to a given ring mode. Asynchronous.
phoneGetRing | Returns the current ring mode of an opened phone device. Synchronous.

Buttons

phoneSetButtonInfo | Sets the information associated with a button on a phone device. Asynchronous.
phoneGetButtonInfo | Returns information associated with a button on a phone device. Synchronous.

Lamps

phoneSetLamp | Lights a lamp on a specified open phone device in a given lamp lighting mode. Asynchronous.
phoneGetLamp | Returns the current lamp mode of the specified lamp. Synchronous.

Data Areas

phoneSetData | Downloads a buffer of data to a given data area in the phone device. Asynchronous.
phoneGetData | Uploads the contents of a given data area in the phone device to a buffer. Synchronous.

Status

phoneSetStatusMessages | Specifies the status changes for which the application wants to be notified. Synchronous.
phoneGetStatusMessages | Returns the status changes for which the application wants to be notified. Synchronous.
phoneGetStatus | Returns the complete status of an open phone device. Synchronous.


Extended Telephony Services Reference

The Extended Telephony functions are listed by category in the following tables.

Extended Telephony Functions for Line Devices

lineNegotiateExtVersion | Allows an application to negotiate an extension version to use with the specified line device. Asynchronous.
lineDevSpecific | Gives service providers access to device-specific features not offered by other TAPI functions. Synchronous.
lineDevSpecificFeature | Sends device-specific switch features to the switch. Asynchronous.

Extended Telephony Functions for Phone Devices

phoneDevSpecific | Device-specific escape function to allow vendor-dependent extensions. Asynchronous.
PhoneNegotiateExtVersion | Allows an application to negotiate an extension version to use with the specified phone device. Synchronous.


Assisted Telephony Services Reference

The Assisted Telephony functions are listed in the following table. Assisted Telephony functions allow any Win32-based application to establish voice calls and media calls. For background information, see the Assisted Telephony overview.

Assisted Telephony Services Functions

tapiRequestMakeCall | Submits a request to place a voice call.
tapiRequestMediaCall | Obsolete. Do not use.
tapiRequestDrop | Obsolete. Do not use.
tapiGetLocationInfo | Returns country code and city/area code information.


TAPI Unicode Support

The following section contains information about support for Unicode.


Functions with Unicode (W) Versions

The following TAPI functions are implemented in Unicode (W) and ANSI (A) versions. In general, the implementation of the ANSI version calls the Unicode version and performs necessary conversions of ANSI parameters and structure fields to and from Unicode; the following table indicates the parameters that are converted.

Applications that explicitly call the generic (neither "W" or "A" suffix) version of a function will execute the ANSI version, for compatibility with previous versions of TAPI.

Note The entire Telephony Service Provider Interface (TSPI) is Unicode for version 2.0.

In the following table, references to string fields in TAPI structures consist of a portion of the field names. For example, the "Caller Address" in the LINEFORWARD structure is pointed to by a field named dwCallerAddressOffset and delimited by a field named dwCallerAddressSize; in the table, this string is identified simply as CallerAddress.

TAPI Function | Parameters and Structure Fields Converted in ANSI Version of Function
lineAddProvider | lpszProviderName
lineBlindTransfer | lpszDestAddress
lineConfigDialog | lpszDeviceClass
lineConfigDialogEdit lpszDeviceClass

Note Application must handle conversion of strings in lpDeviceConfigIn and lpDeviceConfigOut, if these are directly manipulated.

lineDial | lpszDestAddress
lineForward lpForwardList (LINEFORWARDLIST)
  • ForwardList (LINEFORWARD)
    • CallerAddress
    • DestAddress

lpCallParams (LINECALLPARAMS)

  • OrigAddress
  • DisplayableAddress
  • CalledParty
  • Comment
  • TargetAddress
  • DeviceClass
  • CallingPartyID
lineGatherDigits lpsDigits

lpszTerminationDigits

lineGenerateDigits | lpszDigits
lineGetAddressCaps lpAddressCaps (LINEADDRESSCAPS)
  • Address
  • CompletionMsgText
  • DeviceClasses
  • CallTreatmentList (LINECALLTREATMENTENTRY)
  • CallTreatmentName
lineGetAddressID | lpsAddress
lineGetAddressStatus lpAddressStatus (LINEADDRESSSTATUS)
  • Forward (LINEFORWARD)
  • CallerAddress
  • DestAddress
lineGetAgentActivityList lpAgentActivityList (LINEAGENTACTIVITYLIST)
  • List (LINEAGENTACTIVITYENTRY)
  • Name
lineGetAgentCaps lpAgentCaps (LINEAGENTCAPS)
  • AgentHandlerInfo
lineGetAgentGroupList lpAgentGroupListI(LINEAGENTGROUPLIST)
  • List (LINEAGENTGROUPENTRY)
  • Name
lineGetAgentStatus lpAgentStatus (LINEAGENTSTATUS)
  • Activity
  • GroupList (LINEAGENTGROUPENTRY)
  • Name
lineGetAppPriority lpszAppFilename

lpExtensionName

lineGetCallInfo lpCallInfo (LINECALLINFO)
  • CallerID
  • CallerIDName
  • CalledID
  • CalledIDName
  • ConnectID
  • ConnectedIDName
  • RedirectionID
  • RedirectionIDName
  • RedirectingID
  • RedirectingIDName
  • AppName
  • DisplayableAddress
  • CalledParty
  • Comment
lineGetCountry lpLineCountryList (LINECOUNTRYLIST)
  • CountryList (LINECOUNTRYENTRY)
  • CountryName
  • SameAreaRule
  • LongDistanceRule
  • InternationalRule
lineGetDevCaps lpLineDevCaps (LINEDEVCAPS)
  • ProviderInfo
  • SwitchInfo
  • LineName
  • TerminalText
  • DeviceClasses

Note dwStringFormat is obsolete.

LineGetDevConfig lpszDeviceClass

Note Application must handle conversion of strings in lpDeviceConfig, if these are directly manipulated.

LineGetIcon | lpszDeviceClass
lineGetID lpszDeviceClass

Note Application must handle conversion of strings in lpDeviceID, if these are directly manipulated.

LineGetLineDevStatus lpLineDevStatus (LINEDEVSTATUS)
  • AppInfo (LINEAPPINFO)
  • MachineName
  • UserName
  • ModuleFilename
  • FriendlyName
lineGetProviderList lpProviderList (LINEPROVIDERLIST)
  • ProviderList (LINEPROVIDERENTRY)
  • ProviderFilename
lineGetRequest lpRequestBuffer (LINEREQMAKECALL
  • szDestAddress
  • szAppName
  • szCalledParty
  • szComment
lineGetTranslateCaps lpTranslateCaps (LINETRANSLATECAPS)
  • CardList (LINECARDENTRY)
  • CardName
  • SameAreaRule
  • LongDistanceRule
  • InternationalRule
  • LocationList (LINELOCATIONENTRY
  • LocationName
  • CityCode
  • LocalAccessCode
  • LongDistanceAccessCode
  • TollPrefixList
  • celCallWaiting
lineHandoff | lpszFileName
lineInitializeEx | lpszFriendlyAppName
lineMakeCall lpszDestAddress

lpCallParams (LINECALLPARAMS)

  • OrigAddress
  • DisplayableAddress
  • CalledParty
  • Comment
  • TargetAddress
  • DeviceClass
  • CallingPartyID
lineOpen lpCallParams (LINECALLPARAMS)
  • OrigAddress
  • DisplayableAddress
  • CalledParty
  • Comment
  • TargetAddress
  • DeviceClass
  • CallingPartyID
linePark lpszDirAddress

lpNonDirAddress (VARSTRING)

  • String
linePickup lpszDestAddress

lpszGroupID

linePrepareAddToConference lpCallParams (LINECALLPARAMS)
  • OrigAddress
  • DisplayableAddress
  • CalledParty
  • Comment
  • TargetAddress
  • DeviceClass
  • CallingPartyID
lineRedirect | lpszDestAddress
lineSetAppPriority lpszAppFilename

lpszExtensionName

lineSetDevConfig lpszDeviceClass

Note Application must handle conversion of strings in lpDeviceConfig, if these are directly manipulated.

lineSetTollList | lpszAddressIn
lineSetupConference lpCallParams (LINECALLPARAMS)
  • OrigAddress
  • DisplayableAddress
  • CalledParty
  • Comment
  • TargetAddress
  • DeviceClass
  • CallingPartyID
lineSetupTransfer lpCallParams (LINECALLPARAMS)
  • OrigAddress
  • DisplayableAddress
  • CalledParty
  • Comment
  • TargetAddress
  • DeviceClass
  • CallingPartyID
lineTranslateAddress lpszAddressIn

lpTranslateOutput (LINETRANSLATEOUTPUT)

  • DialableString
  • DisplayableString
lineTranslateDialog | lpszAddressIn
lineUnpark | lpszDestAddress
phoneConfigDialog | lpszDeviceClass
phoneGetButtonInfo lpButtonInfo (PHONEBUTTONINFO)
  • ButtonText
phoneGetDevCaps lpPhoneCaps (PHONECAPS)
  • ProviderInfo
  • PhoneInfo
  • PhoneName
  • DeviceClasses

Note dwStringFormat is obsolete.

phoneGetIcon | lpszDeviceClass
phoneGetID lpszDeviceClass

Note Application must handle conversion of strings in lpDeviceID, if these are directly manipulated.

phoneGetStatus lpPhoneStatus (PHONESTATUS)
  • OwnerName
phoneInitializeEx | lpszFriendlyAppName
phoneSetButtonInfo lpButtonInfo (PHONEBUTTONINFO)
  • ButtonTest
tapiGetLocationInfo lpszCountryCode

lpszCityCode

tapiRequestMakeCall lpszDestAddress

lpszAppName

lpszCalledParty

lpszComment


Functions without Unicode Versions

The following functions are provided only in a generic version without an "A" or "W" suffix.

TAPI Function | Comments
lineAccept | The memory pointed to by lpsUserUserInfo is presumed to contain binary data for end-to-end transfer. The application must provide data in a form ready for transmission.
lineAddToConference | —
lineAgentSpecific | The memory pointed to by lpParams is private between the application and agent handler. The application must provide data in the form specified in the agent handler extension definition.
lineAnswer | The memory pointed to by lpsUserUserInfo is presumed to contain binary data for end-to-end transfer. The application must provide data in a form ready for transmission.
lineClose | —
lineCompleteCall | —
lineCompleteTransfer | —
lineConfigProvider | —
lineDeallocateCall | —
lineDevSpecific | The memory pointed to by lpParams is private between the application and service provider. The application must provide data in the form specified in the service provider extension definition.
lineDevSpecificFeature | The memory pointed to by lpParams is private between the application and service provider. The application must provide data in the form specified in the service provider extension definition.
lineDrop | The memory pointed to by lpsUserUserInfo is presumed to contain binary data for end-to-end transfer. The application must provide data in a form ready for transmission.
lineGenerateTone | —
lineGetCallStatus | —
lineGetConfRelatedCalls | —
lineGetNewCalls | —
lineGetMessage | —
lineGetNumRings | —
lineGetStatusMessages | —
lineHold | —
lineMonitorDigits | —
lineMonitorMedia | —
lineMonitorTones | —
lineNegotiateAPIVersion | —
lineNegotiateExtVersion | —
lineProxyMessage | —
lineProxyResponse | The fields in the LINEPROXYREQUEST structure are always Unicode.
lineRegisterRequestRecipient | —
lineReleaseUserUserInfo | —
lineRemoveFromConference | —
lineRemoveProvider | —
lineSecureCall | —
lineSendUserUserInfo | The memory pointed to by lpsUserUserInfo is presumed to contain binary data for end-to-end transfer. The application must provide data in a form ready for transmission.
lineSetAgentActivity | —
lineSetAgentGroup | Note Group names are ignored.
lineSetAgentState | —
lineSetAppSpecific | —
lineSetCallData | The memory pointed to by lpCallData is in a format specified by the application or a group of cooperating applications. The format of the data is beyond the scope of TAPI and is not converted by TAPI.
lineSetCallParams | —
lineSetCallPrivilege | —
lineSetCallQualityOfService | The format of data in the provider-specific portion of the QOS structure is beyond the scope of TAPI and is not converted by TAPI.
lineSetCallTreatment | —
lineSetCurrentLocation | —
lineSetLineDevStatus | —
lineSetMediaControl | —
lineSetMediaMode | —
lineSetNumRings | —
lineSetStatusMessages | —
lineSetTerminal | —
lineShutdown | —
lineSwapHold | —
lineUncompleteCall | —
lineUnhold | —
phoneClose | —
phoneDevSpecific | The memory pointed to by lpParams is private between the application and service provider. The application must provide data in the form specified in the service provider extension definition.
phoneGetData | The memory pointed to by lpData is private between the application and service provider. The application must process data in the form specified in the service provider definition.
phoneGetDisplay | The memory pointed to by lpDisplay is private between the application and service provider. The application must process data in the form specified in the service provider definition.
phoneGetGain | —
phoneGetHookSwitch | —
phoneGetLamp | —
phoneGetMessage | —
phoneGetRing | —
phoneGetStatusMessages | —
phoneGetVolume | —
phoneNegotiateAPIVersion | —
phoneNegotiateExtVersion | —
phoneOpen | —
phoneSetData | The memory pointed to by lpParams is private between the application and service provider. The application must provide data in the form specified in the service provider definition.
phoneSetDisplay | The memory pointed to by lpDisplay is private between the application and service provider. The application must provide data in the form specified in the service provider definition.
phoneSetGain | —
phoneSetHookSwitch | —
phoneSetLamp | —
phoneSetRing | —
phoneSetStatusMessages | —
phoneSetVolume | —
phoneShutdown | —
tapiRequestDrop | This function is obsolete and unavailable to Microsoft® Win32® API applications.
tapiRequestMediaCall | This function is obsolete and unavailable to Microsoft Win32 applications.


TAPI Functions

This section contains an alphabetic list of the line device functions, phone device functions, and assisted telephony functions in the Telephony Application Programming Interface (TAPI). For a categorization of TAPI functions by service level and task, see TAPI Quick Function Reference.

The information for each function includes a list of the valid call states on entry of the function and typical call state transitions when the request is complete. The actual states in which a function can be performed can be further limited by the capabilities of the service provider. Applications must check the dwCallFeatures member in the LINECALLSTATUS structure, the dwAddressFeatures member in the LINEADDRESSSTATUS structure, and the dwLineFeatures member in the LINEDEVSTATUS structure to determine whether or not a function is permitted within the current call state.


Line Device Functions

This section contains an alphabetic listing of the TAPI functions for line devices.

For a categorization of TAPI functions by service level and task, see TAPI Quick Function Reference.


lineAccept

The lineAccept function accepts the specified offered call. It can optionally send the specified user-user information to the calling party.

LONG lineAccept(
  HCALL hCall,
  LPCSTR lpsUserUserInfo,
  DWORD dwSize
);

Parameters

hCall
A handle to the call to be accepted. The application must be an owner of the call. Call state of hCall must be offering.
lpsUserUserInfo
A pointer to a string containing user-user information to be sent to the remote party as part of the call accept. This pointer can be left NULL if no user-user information is to be sent. User-user information is only sent if supported by the underlying network (see LINEDEVCAPS). The protocol discriminator member for the user-user information, if required, should appear as the first byte of the buffer pointed to by lpsUserUserInfo, and must be accounted for in dwSize.
dwSize
The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-user information is sent to the calling party and dwSize is ignored.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds, or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_USERUSERINFOTOOBIG.

Remarks

The lineAccept function is used in telephony environments like Integrated Services Digital Network (ISDN) that allow alerting associated with incoming calls to be separate from the initial offering of the call. When a call comes in, it is first offered. For some small amount of time, the application may have the option to reject the call using lineDrop, redirect the call to another station using lineRedirect, answer the call using lineAnswer, or accept the call using lineAccept. After a call has been successfully accepted by an application, alerting begins at both the called and calling device and the call state typically transitions to accepted.

Alerting is reported to the application by the LINE_LINEDEVSTATE message with the ringing indication.

The lineAccept function may also be supported by non-ISDN service providers. The call state transition to accepted can be used by other applications as an indication that another application has claimed responsibility for the call and has presented the call to the user.

The application has the option to send user-user information at the time of the accept. Even if user-user information is sent, there is no guarantee that the network will deliver this information to the calling party. An application should consult a line's device capabilities to determine whether call accept is available.

For information about the listing of service dependencies, see Service Dependencies.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_REPLY, lineAnswer, LINEDEVCAPS, lineDrop, lineRedirect


lineAddProvider

The lineAddProvider function installs a new telephony service provider into the telephony system.

LONG lineAddProvider(
  LPCSTR lpszProviderFilename,
  HWND hwndOwner,
  LPDWORD lpdwPermanentProviderID
);

Parameters

lpszProviderFilename
A pointer to a NULL-terminated string containing the path of the service provider to be added.
hwndOwner
A handle to a window in which any dialog boxes that need to be displayed as part of the installation process (for example, by the service provider's TSPI_providerInstall function) would be attached. Can be NULL to indicate that any window created during the function should have no owner window.
lpdwPermanentProviderID
A pointer to a DWORD-sized memory location into which TAPI writes the permanent provider identifier of the newly installed service provider.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM, LINEERR_NOMULTIPLEINSTANCE, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED.

Remarks

During this function call, TAPI checks to ensure that it can access the service provider by calling its TSPI_providerInstall function; if this is unsuccessful (if the DLL or function cannot be found, or if TSPI_providerInstall returns an error), the function fails and the provider is not added to the telephony system. If this succeeds, and the Win32 Telephony system is active (one or more applications have called lineInitialize or lineInitializeEx), TAPI does not attempt to launch the newly-added service provider. Instead, in order to activate the new service provider, TAPI issues a message to restart Windows. When the activation succeeds, applications are informed of any new devices created by way of LINE_CREATE or PHONE_CREATE messages, or by a LINE_LINEDEVSTATE message requesting reinitialization (if the application does not support the CREATE messages).

This function copies no files—not the service provider DLL itself nor any supporting files; the application managing the addition of the provider must ensure that the provider is installed in a directory where it can be found by TAPI (for example, \WINDOWS, \WINDOWS\SYSTEM, or elsewhere on the path).

Although this is a new function that older applications would not be expected to call, for backward compatibility they should not be prevented from doing so; the function works the same way for all applications.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_CREATE, LINE_LINEDEVSTATE, lineInitialize, lineInitializeEx, PHONE_CREATE


lineAddToConference

The lineAddToConference function adds the call specified by hConsultCall to the conference call specified by hConfCall.

LONG lineAddToConference(
  HCALL hConfCall,
  HCALL hConsultCall
);

Parameters

hConfCall
A handle to the conference call. The application must be an owner of this call. Any monitoring (media, tones, digits) on a conference call applies only to the hConfCall, not to the individual participating calls. Call state of hConfCall must be onHoldPendingConference or onHold.
hConsultCall
A handle to the call to be added to the conference call. The application must be an owner of this call. This call cannot be a parent of another conference or a participant in any conference. Depending on the device capabilities indicated in LINEADDRESSCAPS, the hConsultCall may not necessarily have been established using lineSetupConference or linePrepareAddToConference. The call state of hConsultCall must be connected, onHold, proceeding, or ringback. Many PBXs allow calls to be added to conferences before they are actually answered.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds, or it is a negative error number if an error occurs. Possible return values are:

LINEERR_CONFERENCEFULL, LINEERR_NOTOWNER, LINEERR_INVALCONFCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

If LINEERR_INVALCALLHANDLE is returned, the specified call handle for the added call is invalid; hConsultCall is a parent of another conference or already a participant in a conference; hConsultCall cannot be added for other reasons (such as, it must have been established using lineSetupConference or linePrepareAddToConference); or hConsultCall and hConfCall are calls on different open lines.

The call handle of the added party remains valid after adding the call to a conference. Its state typically changes to conferenced while the state of the conference call typically becomes connected. Using lineGetConfRelatedCalls, you can obtain a list of call handles that are part of the same conference call as the specified call. The specified call is either a conference call or a participant call in a conference call. New handles are generated for those calls for which the application does not already have handles, and the application is granted monitor privilege to those calls. The handle to an individual participating call can be used later to remove that party from the conference call using lineRemoveFromConference.

If lineGetConfRelatedCalls is called immediately after lineAddToConference, it may not return a complete list of related calls because TAPI waits to receive a LINE_CALLSTATE message indicating that the call has entered LINECALLSTATE_CONFERENCED before it considers the call to actually be part of the conference (that is, the conferenced state is confirmed by the service provider). After the application has received the LINE_CALLSTATE message, lineGetConfRelatedCalls returns complete information.

Note All calls that are part of a conference must exist on the same open line.

The call states of the calls participating in a conference are not independent. For example, when dropping a conference call, all participating calls can automatically become idle. An application should consult the line's device capabilities to determine what form of conference removal is available. The application should track the LINE_CALLSTATE messages to determine what happened to the calls involved.

The conference call is established either by lineSetupConference or lineCompleteTransfer. The call added to a conference is typically established using lineSetupConference or linePrepareAddToConference. Some switches can allow adding arbitrary calls to the conference, and such a call can have been set up using lineMakeCall and be on (hard) hold. The application can examine the dwAddrCapFlags member of the LINEADDRESSCAPS structure to determine the permitted operations.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_CALLSTATE, LINEADDRESSCAPS, lineCompleteTransfer, lineGetConfRelatedCalls, lineMakeCall, linePrepareAddToConference, lineRemoveFromConference, lineSetupConference


lineAgentSpecific

The lineAgentSpecific function allows the application to access proprietary handler-specific functions of the agent handler associated with the address. The meaning of the extensions are specific to the agent handler. Each set of agent-related extensions is identified by a universally unique 128-bit extension ID that must be obtained, along with the specification for the extension, from the promulgator of that extension (usually the author of the agent handler software on the telephony server). The list of extensions supported by the agent handler is obtained from the LINEAGENTCAPS structure returned by lineGetAgentCaps.

LONG lineAgentSpecific(
  HLINE hLine,
  DWORD dwAddressID,
  DWORD dwAgentExtensionIDIndex,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

hLine
A handle to the open line device.
dwAddressID
An address on the open line device.
dwAgentExtensionIDIndex
The position in the ExtensionIDList structure in LINEAGENTCAPS of the agent handler extension being invoked.
lpParams
A pointer to a memory area used to hold a parameter block. The format of this parameter block is device specific and its contents are passed by TAPI to and from the agent handler application on the telephony server. This parameter block must specify the function to be invoked and include sufficient room for any data to be returned.
dwSize
The size in bytes of the parameter block area.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, this function returns one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_INVALAGENTID, LINEERR_INVALLINEHANDLE, LINEERR_INVALPARAM, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_UNINITIALIZED.

Additional return values are specific to the agent handler.

Remarks

This operation is part of the Extended Telephony services. It provides access to an agent handler-specific feature without defining its meaning.

This function provides a generic parameter profile. The interpretation of the parameter structure is handler specific. Indications and replies sent back to the application that are handler specific should use the LINE_AGENTSPECIFIC message.

An agent handler can provide access to handler-specific functions by defining parameters for use with this function. Applications that want to make use of these extensions should consult the vendor-specific documentation that describes what extensions are defined. Typically, an application that relies on these extensions is not able to work with other agent handler environments.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINEAGENTCAPS, lineGetAgentCaps


lineAnswer

The lineAnswer function answers the specified offering call.

LONG lineAnswer(
  HCALL hCall,
  LPCSTR lpsUserUserInfo,
  DWORD dwSize
);

Parameters

hCall
A handle to the call to be answered. The application must be an owner of this call. The call state of hCall must be offering or accepted.
lpsUserUserInfo
A pointer to a string containing user-user information to be sent to the remote party at the time the call is answered. This pointer can be left NULL if no user-user information is to be sent. User-user information is only sent if supported by the underlying network (see LINEDEVCAPS). The protocol discriminator field for the user-user information, if required, should appear as the first byte of the buffer pointed to by lpsUserUserInfo, and must be accounted for in dwSize.
dwSize
The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-user information is sent to the calling party and dwSize is ignored.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INUSE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_USERUSERINFOTOOBIG, LINEERR_NOTOWNER.

Remarks

When a new call arrives, applications with an interest in the call are sent a LINE_CALLSTATE message to provide the new call handle and to inform the application about the call's state and the privileges to the new call (such as monitor or owner). The application with owner privilege for the call can answer this call using lineAnswer. After the call has been successfully answered, the call typically transitions to the connected state. Initially, only one application is given owner privilege to the incoming call.

In some telephony environments (like ISDN), where user alerting is separate from call offering, the application can have the option to accept a call prior to answering or to reject or redirect the offering call.

If a call comes in (is offered) at the time another call is already active, invoking lineAnswer connects to the new call. The effect this has on the existing active call depends on the line's device capabilities. The first call can be unaffected, it can automatically be dropped, or it can automatically be placed on hold. The appropriate LINE_CALLSTATE messages report state transitions to the application about both calls.

In a bridged situation, if a call is connected but in the LINECONNECTEDMODE_INACTIVE state, it can be joined using the lineAnswer function.

The application has the option to send user-user information at the time of the answer. Even if user-user information can be sent, there is no guarantee that the network will deliver this information to the calling party. An application should consult a line's device capabilities to determine whether sending user-user information upon answering the call is available.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINE_CALLSTATE, LINE_REPLY, LINEDEVCAPS


lineBlindTransfer

The lineBlindTransfer function performs a blind or single-step transfer of the specified call to the specified destination address.

LONG lineBlindTransfer(
  HCALL hCall,
  LPCSTR lpszDestAddress,
  DWORD dwCountryCode
);

Parameters

hCall
A handle to the call to be transferred. The application must be an owner of this call. The call state of hCall must be connected.
lpszDestAddress
A pointer to a NULL-terminated string identifying where the call is to be transferred to. The destination address uses the standard dialable number format.
dwCountryCode
The country code of the destination. This is used by the implementation to select the call progress protocols for the destination address. If a value of 0 is specified, a default call-progress protocol defined by the service provider is used.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_INVALCOUNTRYCODE, LINEERR_INVALCALLSTATE, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONUNAVAIL, LINEERR_NOTOWNER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALADDRESS, LINEERR_UNINITIALIZED, LINEERR_ADDRESSBLOCKED, LINEERR_OPERATIONFAILED.

Remarks

If LINEERR_INVALADDRESS is returned, no dialing occurs.

Blind transfer differs from a consultation transfer in that no consultation call is made visible to the application. After the blind transfer successfully completes, the specified call is typically cleared from the application's line, and it transitions to the idle state.

The application's call handle remains valid after the transfer has completed. The application must deallocate its handle using lineDeallocateCall when it is no longer interested in the transferred call.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_REPLY, lineDeallocateCall


lineCallbackFunc

The lineCallbackFunc function is a placeholder for the application-supplied function name.

VOID FAR PASCAL lineCallbackFunc(
  DWORD hDevice,
  DWORD dwMsg,
  DWORD dwCallbackInstance,
  DWORD dwParam1,
  DWORD dwParam2,
  DWORD dwParam3
);

Parameters

hDevice
A handle to either a line device or a call associated with the callback. The nature of this handle (line handle or call handle) can be determined by the context provided by dwMsg. Applications must use the DWORD type for this parameter because using the HANDLE type may generate an error.
dwMsg
A line or call device message.
dwCallbackInstance
Callback instance data passed back to the application in the callback. This DWORD is not interpreted by TAPI.
dwParam1
A parameter for the message.
dwParam2
A parameter for the message.
dwParam3
A parameter for the message.

Remarks

For information about parameter values passed to this function, see Line Device Messages.

All callbacks occur in the application's context. The callback function must reside in a DLL or application module.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with user-defined.


lineClose

The lineClose function closes the specified open line device.

LONG lineClose(
  HLINE hLine
);

Parameters

hLine
A handle to the open line device to be closed. After the line has been successfully closed, this handle is no longer valid.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL.

Remarks

If an application calls lineClose while it still has active calls on the opened line, the application's ownership of these calls is revoked. If the application was the sole owner of these calls, the calls are dropped as well. It is good programming practice for an application to dispose of the calls it owns on an opened line by explicitly relinquishing ownership and/or by dropping these calls prior to closing the line.

If the line was closed successfully, a LINE_LINEDEVSTATE message is sent to all applications that are monitoring the line status of open/close changes. Outstanding asynchronous replies are suppressed.

Service providers may find it useful or necessary to forcibly reclaim line devices from an application that has the line open. This can be useful to prevent an application from monopolizing the line device for too long. If this happens, a LINE_CLOSE message is sent to the application, specifying the line handle of the line device that was closed.

The lineOpen function allocates resources to the invoking application, and applications can be prevented from opening a line if resources are unavailable. Therefore, an application that only occasionally uses a line device (such as for making outgoing calls) should close the line to free resources and allow other applications to open the line.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINE_CLOSE, LINE_LINEDEVSTATE, lineOpen


lineCompleteCall

The lineCompleteCall function specifies how a call that could not be connected normally should be completed instead. The network or switch may not be able to complete a call because network resources are busy or the remote station is busy or doesn't answer. The application can request that the call be completed in one of a number of ways.

LONG lineCompleteCall(
  HCALL hCall,
  LPDWORD lpdwCompletionID,
  DWORD dwCompletionMode,
  DWORD dwMessageID
);

Parameters

hCall
A handle to the call whose completion is requested. The application must be an owner of the call. The call state of hCall must be busy, ringback.
lpdwCompletionID
A pointer to a DWORD-sized memory location. The completion identifier is used to identify individual completion requests in progress. A completion identifier becomes invalid and can be reused after the request completes or after an outstanding request is canceled.
dwCompletionMode
The way in which the call is to be completed. Note that dwCompletionMode is allowed to have only a single flag set. This parameter uses the following LINECALLCOMPLMODE_ constants:
LINECALLCOMPLMODE_CAMPON
Queues the call until the call can be completed. The call remains in the busy state while queued.
LINECALLCOMPLMODE_CALLBACK
Requests the called station to return the call when it returns to idle.
LINECALLCOMPLMODE_INTRUDE
Adds the application to the existing physical call at the called station (barges in).
LINECALLCOMPLMODE_MESSAGE
Leave a short predefined message for the called station ("Leave Word Calling"). The message to be sent is specified by dwMessageID.
dwMessageID
The message that is to be sent when completing the call using LINECALLCOMPLMODE_MESSAGE. This identifier selects the message from a small number of predefined messages.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_COMPLETIONOVERRUN, LINEERR_NOMEM, LINEERR_INVALCALLCOMPLMODE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALMESSAGEID, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED.

Remarks

This function is considered complete when the request has been accepted by the network or switch; not when the request is fully completed in the way specified. After this function completes, the call typically transitions to idle. When the called station or network enters a state where the call can be completed as requested, the application is notified by a LINE_CALLSTATE message with the call state equal to offering. The call's LINECALLINFO record lists the reason for the call as CALLCOMPLETION and provides the completion identifier as well. It is possible to have multiple outstanding call completion requests; the maximum number is device dependent. The completion identifier is also used to refer to each individual request so requests can be canceled by calling lineUncompleteCall.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_CALLSTATE, LINE_REPLY, LINECALLINFO, lineUncompleteCall


lineCompleteTransfer

The lineCompleteTransfer function completes the transfer of the specified call to the party connected in the consultation call.

LONG lineCompleteTransfer(
  HCALL hCall,
  HCALL hConsultCall,
  LPHCALL lphConfCall,
  DWORD dwTransferMode
);

Parameters

hCall
A handle to the call to be transferred. The application must be an owner of this call. The call state of hCall must be onHold, onHoldPendingTransfer.
hConsultCall
A handle to the call that represents a connection with the destination of the transfer. The application must be an owner of this call. The call state of hConsultCall must be connected, ringback, busy, or proceeding.
lphConfCall
A pointer to a memory location where an hCall handle can be returned. If dwTransferMode is LINETRANSFERMODE_CONFERENCE, the newly created conference call is returned in lphConfCall and the application becomes the sole owner of the conference call. Otherwise, this parameter is ignored by TAPI.
dwTransferMode
Specifies how the initiated transfer request is to be resolved. This parameter uses the following LINETRANSFERMODE_ constants:
LINETRANSFERMODE_TRANSFER
Resolve the initiated transfer by transferring the initial call to the consultation call.
LINETRANSFERMODE_CONFERENCE
Resolve the initiated transfer by conferencing all three parties into a three-way conference call. A conference call is created and returned to the application.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCONSULTCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALTRANSFERMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

The LINE_REPLY message sent in response to a call to the lineCompleteTransfer function is based on the status of the call specified by the hCall parameter.

This operation completes the transfer of the original call, hCall, to the party currently connected by hConsultCall. The consultation call is typically dialed on the consultation call allocated as part of lineSetupTransfer, but it can be any call to which the switch is capable of transferring hCall.

The transfer request can be resolved either as a transfer or as a three-way conference call. When resolved as a transfer, the parties connected by hCall and hConsultCall are connected to each other, and both hCall and hConsultCall are typically cleared from the application's line and transition to the idle state. The application's call handle remains valid after the transfer has completed. The application must deallocate its handle with lineDeallocateCall when it is no longer interested in the transferred call.

When resolved as a conference, all three parties enter into a conference call. Both existing call handles remain valid but transition to the conferenced state. A conference call handle is created and returned, and it transitions to the connected state.

If lineGetConfRelatedCalls is called immediately after lineCompleteTransfer with the result that the calls are conferenced, lineGetConfRelatedCalls may not return a complete list of related calls. This is because TAPI waits to receive a LINE_CALLSTATE message indicating that the call has entered LINECALLSTATE_CONFERENCED before it considers the call to actually be part of the conference. That is, it waits for the service provider to confirm the conferenced state. After the application has received the LINE_CALLSTATE message, lineGetConfRelatedCalls returns complete information.

It can also be possible to perform a blind transfer of a call using lineBlindTransfer.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_CALLSTATE, LINE_REPLY, lineBlindTransfer, lineDeallocateCall, lineGetConfRelatedCalls, lineSetupTransfer


lineConfigDialog

The lineConfigDialog function causes the provider of the specified line device to display a dialog box (attached to hwndOwner of the application) to allow the user to configure parameters related to the line device.

LONG lineConfigDialog(
  DWORD dwDeviceID,
  HWND hwndOwner,
  LPCSTR lpszDeviceClass
);

Parameters

dwDeviceID
The line device to be configured.
hwndOwner
A handle to a window to which the dialog box is to be attached. Can be NULL to indicate that any window created during the function should have no owner window.
lpszDeviceClass
A pointer to a NULL-terminated string that identifies a device class name. This device class allows the application to select a specific subscreen of configuration information applicable to that device class. This parameter is optional and can be left NULL or empty, in which case the highest level configuration is selected.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_OPERATIONFAILED, LINEERR_INVALDEVICECLASS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_UNINITIALIZED, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_NODEVICE.

Remarks

The lineConfigDialog function causes the service provider to display a modal dialog box (attached to hwndOwner of the application) to allow the user to configure parameters related to the line specified by dwDeviceID. The lpszDeviceClass parameter allows the application to select a specific subscreen of configuration information applicable to the device class in which the user is interested; the permitted strings are the same as for lineGetID. For example, if the line supports the Comm API, passing "COMM" as lpszDeviceClass causes the provider to display the parameters related specifically to Comm (or, at least, start at the corresponding point in a multilevel configuration dialog box chain, so the user doesn't have to "dig" to find the parameters of interest).

The lpszDeviceClass parameter would be "tapi/line" , "", or NULL to cause the provider to display the highest level configuration for the line.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, lineGetID


lineConfigDialogEdit

The lineConfigDialogEdit function causes the provider of the specified line device to display a dialog box (attached to hwndOwner of the application) to allow the user to configure parameters related to the line device.

LONG lineConfigDialogEdit(
  DWORD dwDeviceID,
  HWND hwndOwner,
  LPCSTR lpszDeviceClass,
  LPVOID const lpDeviceConfigIn,
  DWORD dwSize,
  LPVARSTRING lpDeviceConfigOut
);

Parameters

dwDeviceID
The line device to be configured.
hwndOwner
A handle to a window to which the dialog box is to be attached. Can be NULL to indicate that any window created during the function should have no owner window.
lpszDeviceClass
A pointer to a NULL-terminated string that identifies a device class name. This device class allows the application to select a specific subscreen of configuration information applicable to that device class. This parameter is optional and can be left NULL or empty, in which case the highest level configuration is selected.
lpDeviceConfigIn
A pointer to the opaque configuration data structure that was returned by lineGetDevConfig (or a previous invocation of lineConfigDialogEdit) in the variable portion of the VARSTRING structure.
dwSize
The number of bytes in the structure pointed to by lpDeviceConfigIn. This value is returned in the dwStringSize member in the VARSTRING structure returned by lineGetDevConfig or a previous invocation of lineConfigDialogEdit.
lpDeviceConfigOut
A pointer to the memory location of type VARSTRING where the device configuration structure is returned. Upon successful completion of the request, this location is filled with the device configuration. The dwStringFormat member in the VARSTRING structure is set to STRINGFORMAT_BINARY. Prior to calling lineGetDevConfig (or a future invocation of lineConfigDialogEdit), the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_OPERATIONFAILED, LINEERR_INVALDEVICECLASS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM, LINEERR_NODEVICE.

Remarks

If LINEERR_STRUCTURETOOSMALL is returned, the dwTotalSize member of the VARSTRING structure pointed to by lpDeviceConfigOut does not specify enough memory to contain the entire configuration structure. The dwNeededSize member has been set to the amount required. To the extent that user entries were reflected in information that could not be returned due to insufficient space, those edits are lost; applications should therefore allocate the maximum amount of space that may be needed by the device class to return its configuration structure (for more information, see TAPI Device Classes).

The lineConfigDialogEdit function causes the service provider to display a modal dialog box (attached to hwndOwner of the application) to allow the user to configure parameters related to the line specified by dwDeviceID.

The lpszDeviceClass parameter allows the application to select a specific subscreen of configuration information applicable to the device class in which the user is interested; the permitted strings are the same as for lineGetID. For example, if the line supports the Comm API, passing "COMM" as lpszDeviceClass causes the provider to display the parameters related specifically to Comm (or, at least, start at the corresponding point in a multilevel configuration dialog box chain, so the user doesn't have to "dig" to find the parameters of interest).

The lpszDeviceClass parameter would be "tapi/line" , "", or NULL to cause the provider to display the highest level configuration for the line.

The difference between this function and lineConfigDialog is the source of the parameters to edit and the result of the editing. In lineConfigDialog, the parameters edited are those currently in use on the device (or set for use on the next call), and any changes made have (to the maximum extent possible) an immediate impact on any active connection; also, the application must use lineGetDevConfig to fetch the result of parameter changes from lineConfigDialog. With lineConfigDialogEdit, the parameters to edit are passed in from the application, and the results are returned to the application, with no impact on active connections; the results of the editing are returned with this function, and the application does not need to call lineGetDevConfig. Thus, lineConfigDialogEdit permits an application to provide the ability for the user to set up parameters for future calls without having an impact on any active call. However, the output of this function can be passed to lineSetDevConfig to affect the current call or next call.

Although this is a new function that older applications would not be expected to call, for backward compatibility they should not be prevented from doing so; the function works the same way for all applications.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, lineConfigDialog, lineGetDevConfig, lineGetID, lineSetDevConfig, VARSTRING


lineConfigProvider

The lineConfigProvider function causes a service provider to display its configuration dialog box.

LONG lineConfigProvider(
  HWND hwndOwner,
  DWORD dwPermanentProviderID
);

Parameters

hwndOwner
A handle to a window to which the configuration dialog box (displayed by TSPI_providerConfig) is attached. Can be NULL to indicate that any window created during the function should have no owner window.
dwPermanentProviderID
The permanent provider identifier of the service provider to be configured.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM, LINEERR_OPERATIONFAILED.

Remarks

This is basically a straight pass-through to TSPI_providerConfig.

Although this is a new function that older applications would not be expected to call, for backward compatibility they should not be prevented from doing so; the function works the same way for all applications.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions


lineDeallocateCall

The lineDeallocateCall function deallocates the specified call handle.

LONG lineDeallocateCall(
  HCALL hCall
);

Parameters

hCall
The call handle to be deallocated. An application with monitoring privileges for a call can always deallocate its handle for that call. An application with owner privilege for a call can deallocate its handle unless it is the sole owner of the call and the call is not in the idle state. The call handle is no longer valid after it has been deallocated.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

The deallocation does not affect the call state of the physical call. It does, however, release internal resources related to the call.

In API versions earlier than 2.0, if the application is the sole owner of a call and the call is not in the idle state, LINEERR_INVALCALLSTATE is returned. In this case, the application can first drop the call using lineDrop and deallocate its call handle afterwards. An application that has monitor privilege for a call can always deallocate its handle for the call.

In API versions 2.0 or later, the sole owner of the call can deallocate its handle even though the call is not in the idle state. (This allows for distributed control of the call in a client/server environment.)

Note Be aware that leaving the call without an owner can result in the user being unable to terminate the call if there are monitoring applications open preventing TAPI from calling TSPI_lineCloseCall. Use this feature only if the application can determine that the call can be controlled externally by the user (see LINEADDRCAPFLAGS_CLOSEDROP).

In API versions earlier than 2.0, when the lineDeallocateCall function deallocates a call handle, it also suspends further processing of any outstanding LINE_REPLY messages for the call. An application must be designed not to wait indefinitely for LINE_REPLY messages for each corresponding call to an asynchronous function if it also uses the lineDeallocateCall function to deallocate handles.

In API versions 2.0 or later, lineDeallocateCall does not suspend outstanding LINE_REPLY messages; every asynchronous function that returns a dwRequestID to the application always results in the delivery of the associated LINE_REPLY message unless the application calls lineShutdown.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINE_REPLY, lineDrop, lineShutdown


lineDevSpecific

The lineDevSpecific function enables service providers to provide access to features not offered by other TAPI functions. The meaning of the extensions are device specific, and taking advantage of these extensions requires the application to be fully aware of them.

LONG lineDevSpecific(
  HLINE hLine,
  DWORD dwAddressID,
  HCALL hCall,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

hLine
A handle to a line device. This parameter is required.
dwAddressID
An address identifier on the given line device.
hCall
A handle to a call. This parameter is optional, but if it is specified, the call it represents must belong to the hLine line device. The call state of hCall is device specific.
lpParams
A pointer to a memory area used to hold a parameter block. The format of this parameter block is device specific and its contents are passed by TAPI to or from the service provider.
dwSize
The size in bytes of the parameter block area.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds, or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Additional return values are device specific.

Remarks

This operation is part of the Extended Telephony services. It provides access to a device-specific feature without defining its meaning. This operation is only available if the application has successfully negotiated a device-specific extension version.

This function provides a generic parameter profile. The interpretation of the parameter structure is device specific. Whether dwAddressID and/or hCall are expected to be valid is device specific. If specified, they must belong to hLine. Indications and replies sent back the application that are device specific should use the LINE_DEVSPECIFIC message.

A service provider can provide access to device-specific functions by defining parameters for use with this function. Applications that want to make use of these device-specific extensions should consult the device-specific (in this case, vendor-specific) documentation that describes what extensions are defined. Typically, an application that relies on these device-specific extensions is not able to work with other service provider environments.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Extended Telephony Services Reference, LINE_DEVSPECIFIC, LINE_REPLY


lineDevSpecificFeature

The lineDevSpecificFeature function enables service providers to provide access to features not offered by other TAPI functions. The meaning of these extensions are device specific, and taking advantage of these extensions requires the application to be fully aware of them.

LONG lineDevSpecificFeature(
  HLINE hLine,
  DWORD dwFeature,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

hLine
A handle to the line device.
dwFeature
The feature to invoke on the line device. This parameter uses the PHONEBUTTONFUNCTION_ constants.
lpParams
A pointer to a memory area used to hold a feature-dependent parameter block. The format of this parameter block is device specific and its contents are passed through by TAPI to or from the service provider.
dwSize
The size of the buffer in bytes.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALFEATURE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Additional return values are device specific.

Remarks

This operation is part of the Extended Telephony services. It provides access to a device-specific feature without defining its meaning. This operation is only available if the application has successfully negotiated a device-specific extension version.

This function provides the application with phone feature-button emulation capabilities. When an application invokes this operation, it specifies the equivalent of a button-press event. This method of invoking features is device dependent, as TAPI does not define their meaning. Typically, an application that relies on these device-specific extensions does not work with other service provider environments.

The structure pointed to by lpParams should not contain any pointers because they would not be properly translated (thunked) when running a 16-bit application in a 32-bit version of TAPI and vice versa.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Extended Telephony Services Reference, LINE_REPLY


lineDial

The lineDial function dials the specified dialable number on the specified call.

LONG lineDial(
  HCALL hCall,
  LPCSTR lpszDestAddress,
  DWORD dwCountryCode
);

Parameters

hCall
A handle to the call on which a number is to be dialed. The application must be an owner of the call. The call state of hCall can be any state except idle and disconnected.
lpszDestAddress
The destination to be dialed using the standard dialable number format.
dwCountryCode
The country code of the destination. This is used by the implementation to select the call progress protocols for the destination address. If a value of 0 is specified, a service provider-defined default call progress protocol is used.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_ADDRESSBLOCKED, LINEERR_INVALPOINTER, LINEERR_DIALBILLING, LINEERR_NOMEM, LINEERR_DIALDIALTONE, LINEERR_NOTOWNER, LINEERR_DIALPROMPT, LINEERR_OPERATIONFAILED, LINEERR_DIALQUIET, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_UNINITIALIZED, LINEERR_INVALCOUNTRYCODE.

Remarks

If LINEERR_INVALADDRESS is returned, no dialing has been done. If LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE, or LINEERR_DIALPROMPT is returned, none of the actions otherwise performed by lineDial have occurred. For example, none of the dialable addresses prior to the offending character has been dialed, no hookswitch state has changed, and so on.

The lineDial function is used for dialing on an existing call appearance. For example, after a call has been set up for transfer or conference, a consultation call is automatically allocated, and the lineDial function would be used to perform the dialing of this consultation call. The lineDial function can be invoked multiple times in the course of multistage dialing, if the line's device capabilities allow it. Also, multiple addresses can be provided in a single dial string separated by CRLF. Service providers that provide inverse multiplexing can establish individual physical calls with each of the addresses and can return a single call handle to the aggregate of all calls to the application. All addresses would use the same country code.

Dialing is considered complete after the address has been passed to the service provider; not after the call is finally connected. Service providers that provide inverse multiplexing can allow multiple addresses to be provided at once. The service provider sends LINE_CALLSTATE messages to the application to inform it about the progress of the call. To abort a call attempt while a call is being established, the invoking application should use lineDrop.

An application can set the lpszDestAddress parameter of the lineDial function to the address of an empty string to indicate that dialing is complete, but only if the previous calls to the lineMakeCall and lineDial functions have had the strings specified by lpszDestAddress terminated with semicolons.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINE_CALLSTATE, LINE_REPLY, lineDrop, lineMakeCall


lineDrop

The lineDrop function drops or disconnects the specified call. The application has the option to specify user-user information to be transmitted as part of the call disconnect.

LONG lineDrop(
  HCALL hCall,
  LPCSTR lpsUserUserInfo,
  DWORD dwSize
);

Parameters

hCall
A handle to the call to be dropped. The application must be an owner of the call. The call state of hCall can be any state except idle.
lpsUserUserInfo
A pointer to a string containing user-user information to be sent to the remote party as part of the call disconnect. This pointer can be left NULL if no user-user information is to be sent. User-user information is only sent if supported by the underlying network (see LINEDEVCAPS). The protocol discriminator field for the user-user information, if required, should appear as the first byte of the buffer pointed to by lpsUserUserInfo, and must be accounted for in dwSize.
dwSize
The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-user information is sent to the calling party and dwSize is ignored.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_NOTOWNER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_USERUSERINFOTOOBIG, LINEERR_INVALCALLSTATE, LINEERR_UNINITIALIZED.

Remarks

When invoking lineDrop, related calls can sometimes be affected as well. For example, dropping a conference call can drop all individual participating calls. LINE_CALLSTATE messages are sent to the application for all calls whose call state is affected. A dropped call typically transitions to the idle state. Invoking lineDrop on a call in the offering state rejects the call. Not all telephone networks provide this capability.

A call in the onholdpending state typically reverts to the connected state. When dropping the consultation call to the third party for a conference call or when removing the third party in a previously established conference call, the provider (and switch) can release the conference bridge and revert the call back to a normal two-party call. If this is the case, hConfCall transitions to the idle state, and the only remaining participating call transitions to the connected state. Some switches automatically "unhold" the other call.

The application has the option to send user-user information at the time of the drop. Even if user-user information can be sent, there is no guarantee that the network will deliver this information to the remote party.

In various bridged or party-line configurations when multiple parties are on the call, lineDrop may not actually clear the call. For example, in a bridged situation, a lineDrop operation may not actually drop the call because the status of other stations on the call may govern; instead, the call may simply be changed to the LINECONNECTEDMODE_INACTIVE mode if it remains connected at other stations.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, Basic Telephony Services Reference


lineForward

The lineForward function forwards calls destined for the specified address on the specified line, according to the specified forwarding instructions. When an originating address (dwAddressID) is forwarded, the specified incoming calls for that address are deflected to the other number by the switch. This function provides a combination of forward and do-not-disturb features. This function can also cancel forwarding currently in effect.

LONG lineForward(
  HLINE hLine,
  DWORD bAllAddresses,
  DWORD dwAddressID,
  LPLINEFORWARDLIST const lpForwardList,
  DWORD dwNumRingsNoAnswer,
  LPHCALL lphConsultCall,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

hLine
A handle to the line device.
bAllAddresses
Specifies whether all originating addresses on the line or just the one specified is to be forwarded. If TRUE, all addresses on the line are forwarded and dwAddressID is ignored; if FALSE, only the address specified as dwAddressID is forwarded.
dwAddressID
The address on the specified line whose incoming calls are to be forwarded. This parameter is ignored if bAllAddresses is TRUE.
lpForwardList
A pointer to a variably sized data structure that describes the specific forwarding instructions, of type LINEFORWARDLIST.
dwNumRingsNoAnswer
The number of rings before a call is considered a "no answer." If dwNumRingsNoAnswer is out of range, the actual value is set to the nearest value in the allowable range.
lphConsultCall
A pointer to an HCALL location. In some telephony environments, this location is loaded with a handle to a consultation call that is used to consult the party that is being forwarded to, and the application becomes the initial sole owner of this call. This pointer must be valid even in environments where call forwarding does not require a consultation call. This handle is set to NULL if no consultation call is created.
lpCallParams
A pointer to a structure of type LINECALLPARAMS. This pointer is ignored unless lineForward requires the establishment of a call to the forwarding destination (and lphConsultCall is returned, in which case lpCallParams is optional). If NULL, default call parameters are used. Otherwise, the specified call parameters are used for establishing hConsultCall.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPARAM, LINEERR_UNINITIALIZED.

Remarks

A successful forwarding indicates only that the request has been accepted by the service provider, not that forwarding is set up at the switch. A LINE_ADDRESSSTATE (forwarding) message provides confirmation for forwarding having been set up at the switch.

Forwarding of the address(es) remains in effect until this function is called again. The most recent forwarding list replaces the old one. Forwarding can be canceled by specifying a NULL pointer as lpForwardList. If a NULL destination address is specified for an entry in the forwarding list, the operation acts as a do-not-disturb.

Forwarding status of an address can also be affected externally; for example, by administrative actions at the switch or by a user from another station. It may not be possible for the service provider to be aware of this state change, and it may not be able to keep in synchronization with the forwarding state known to the switch.

Because a service provider may not know the forwarding state of the address "for sure" (that is, it may have been forwarded or unforwarded in an unknown way), lineForward succeeds unless it fails to set the new forwarding instructions. In other words, a request that all forwarding be canceled at a time that there is no forwarding in effect is successful. This is because there is no "unforwarding"—you can only change the previous set of forwarding instructions.

The success or failure of this operation does not depend on the previous set of forwarding instructions, and the same is true when setting different forwarding instructions. The provider should "unforward everything" prior to setting the new forwarding instructions. Because this can take time in analog telephony environments, a provider may also want to compare the current forwarding with the new one, and only issue instructions to the switch to get to the final state (leaving unchanged forwarding unaffected).

Invoking lineForward when LINEFORWARDLIST has dwNumEntries set to zero has the same effect as providing a NULL lpForwardList parameter. It cancels all forwarding currently in effect.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_ADDRESSSTATE, LINE_REPLY, LINECALLPARAMS, LINEFORWARDLIST


lineGatherDigits

The lineGatherDigits function initiates the buffered gathering of digits on the specified call. The application specifies a buffer in which to place the digits and the maximum number of digits to be collected.

LONG lineGatherDigits(
  HCALL hCall,
  DWORD dwDigitModes,
  LPSTR lpsDigits,
  DWORD dwNumDigits,
  LPCSTR lpszTerminationDigits,
  DWORD dwFirstDigitTimeout,
  DWORD dwInterDigitTimeout
);

Parameters

hCall
A handle to the call on which digits are to be gathered. The application must be an owner of the call. The call state of hCall can be any state.
dwDigitModes
The digit mode(s) to be monitored. Note that dwDigitModes is allowed to have one or more flags set. This parameter uses the following LINEDIGITMODE_ constants:
LINEDIGITMODE_PULSE
Detect digits as audible clicks that are the result of the use of rotary pulse sequences. Valid digits for pulse mode are '0' through '9'.
LINEDIGITMODE_DTMF
Detect digits as DTMF tones. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.
lpsDigits
A pointer to the buffer where detected digits are to be stored as ASCII characters. Digits may not show up in the buffer one at a time as they are collected. Only after a LINE_GATHERDIGITS message is received should the content of the buffer be assumed to be valid. If lpsDigits is NULL, the digit gathering currently in progress on the call is terminated and dwNumDigits is ignored. Otherwise, lpsDigits is assumed to have room for dwNumDigits digits.
dwNumDigits
The number of digits to be collected before a LINE_GATHERDIGITS message is sent to the application. The dwNumDigits parameter is ignored when lpsDigits is NULL. This function fails if dwNumDigits is zero.
lpszTerminationDigits
Specifies a NULL-terminated string of termination digits as ASCII characters. If one of the digits in the string is detected, that termination digit is appended to the buffer, digit collection is terminated, and the LINE_GATHERDIGITS message is sent to the application.

Valid characters for pulse mode are '0' through '9'. Valid characters for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'. If this pointer is NULL, or if it points to an empty string, the function behaves as though no termination digits were supplied.

dwFirstDigitTimeout
The time duration in milliseconds in which the first digit is expected. If the first digit is not received in this timeframe, digit collection is aborted and a LINE_GATHERDIGITS message is sent to the application. The buffer only contains the NULL character, indicating that no digits were received and the first digit timeout terminated digit gathering. The call's line-device capabilities specify the valid range for this parameter or indicate that timeouts are not supported.
dwInterDigitTimeout
The maximum time duration in milliseconds between consecutive digits. If no digit is received in this timeframe, digit collection is aborted and a LINE_GATHERDIGITS message is sent to the application. The buffer only contains the digits collected up to this point followed by a NULL character, indicating that an interdigit timeout terminated digit gathering. The call's line-device capabilities specify the valid range for this parameter or indicate that timeouts are not supported.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_NOTOWNER, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED.

Remarks

Digit collection is terminated when the requested number of digits has been collected. It is also terminated when one of the digits detected matches a digit in szTerminationDigits before the specified number of digits has been collected. The detected termination digit is also placed in the buffer and the partial buffer is returned.

Another way of canceling digit collection occurs when one of the timeouts expires. The dwFirstDigitTimeout expires if the first digit is not received in this time period. The dwInterDigitTimout expires if the second, third, (and so forth) digit is not received within that time period from the previously detected digit, and a partial buffer is returned.

A fourth method for terminating digit collection is by calling this function again while collection is in progress. The old collection session is terminated, any digits collected up to that point are copied to the buffer supplied from the previous call to this function, and the buffer is delivered when the LINE_GATHERDIGITS message is sent to the application. The mechanism for terminating digit gathering without initiating another gathering of the digits is to invoke this function with lpsDigits equal to NULL.

This function is considered successful if digit collection has been correctly initiated, not if digit collection has terminated. In all cases where a partial buffer is returned, valid digits (if any) are followed by an ASCII NULL character.

Although this function can be invoked in any call state, digits can typically only be gathered while the call is in the connected state.

The message LINE_GATHERDIGITS is sent only to the application that initiated the request. It is also sent when partial buffers are returned because of timeouts or matching termination digits, or when the request is canceled by another lineGatherDigits request on the call. Only one gather-digits request can be active on a call at any given time across all applications that are owners of the call. Given the asynchronous behavior of the operation, an application that issues multiple lineGatherDigits requests in quick succession may be able to do so and receive several LINE_GATHERDIGITS messages later. While this would be unusual application behavior, the application is able to count the number of these messages to allow cancel messages to be matched with the earlier requests. In any case, only the most recent request should be assumed to be valid.

Note When an application invokes any asynchronous operation that writes data back into application memory, the application must keep that memory available for writing until a LINE_REPLY or LINE_GATHERDIGITS message is received.

An application can use lineMonitorDigits to enable or disable unbuffered digit detection. Each time a digit is detected in this fashion, a LINE_MONITORDIGITS message is sent to the application. Both buffered and unbuffered digit detection can be simutaneously enabled for the same call.

Gathering of digits on a conference call applies only to the hConfCall, not to the individual participating calls.

If the lineGatherDigits function is used to cancel a previous request to gather digits, the function copies any digits collected up to that point to the buffer specified in the original function call. The function then sends a LINE_GATHERDIGITS message to the application, regardless of whether the lpszDigits parameter in the second call specifies a NULL or different address.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_GATHERDIGITS, LINE_REPLY, LINE_MONITORDIGITS, lineMonitorDigits


lineGenerateDigits

The lineGenerateDigits function initiates the generation of the specified digits on the specified call as inband tones using the specified signaling mode. Invoking this function with a NULL value for lpszDigits aborts any digit generation currently in progress. Invoking lineGenerateDigits or lineGenerateTone while digit generation is in progress aborts the current digit generation or tone generation and initiates the generation of the most recently specified digits or tone.

LONG lineGenerateDigits(
  HCALL hCall,
  DWORD dwDigitMode,
  LPCSTR lpszDigits,
  DWORD dwDuration
);

Parameters

hCall
A handle to the call. The application must be an owner of the call. Call state of hCall can be any state.
dwDigitMode
The format to be used for signaling these digits. Note that dwDigitMode is allowed to have only a single flag set. This parameter uses the following LINEDIGITMODE_ constants:
LINEDIGITMODE_PULSE
Uses pulse/rotary for digit signaling. Valid digits for pulse mode are '0' through '9'.
LINEDIGITMODE_DTMF
Uses DTMF tones for digit signaling. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.
lpszDigits
A pointer to a NULL-terminated character buffer that contains the digits to be generated. Valid characters for pulse mode are '0' through '9' and ',' (comma). Valid characters for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#', and ',' (comma). A comma injects an extra delay between the signaling of the previous and next digits it separates. The duration of this pause is configuration defined, and the line's device capabilities indicate what this duration is. Multiple commas can be used to inject longer pauses. Invalid digits are ignored during the generation, rather than being reported as errors. The exclamation character (!) is a valid character in the string specifed by the lpszDigits parameter for both DTMF and pulse mode. This character causes a "hookflash" operation, as described for dialable addresses.
dwDuration
Both the duration in milliseconds of DTMF digits and pulse and DTMF inter-digit spacing. A value of 0 uses a default value. The dwDuration parameter must be within the range specified by MinDialParams and MaxDialParams in LINEDEVCAPS. If out of range, the actual value is set to the nearest value in the range.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

The lineGenerateDigits function is considered to have completed successfully when the digit generation has been successfully initiated, not when all digits have been generated. In contrast to lineDial, which dials digits in a network-dependent fashion, lineGenerateDigits guarantees to produce the digits as inband tones over the voice channel using DTMF or hookswitch dial pulses when using pulse. The lineGenerateDigits function is generally not suitable for making calls or dialing. It is intended for end-to-end signaling over an established call.

After all digits in lpszDigits have been generated, or after digit generation has been aborted or canceled, a LINE_GENERATE message is sent to the application.

Only one inband generation request (tone generation or digit generation) is allowed to be in progress per call across all applications that are owners of the call. Digit generation on a call is canceled by initiating either another digit generation request or a tone generation request. To cancel the current digit generation, the application can invoke lineGenerateDigits and specify NULL for the lpszDigits parameter.

Depending on the service provider and hardware, the application can monitor the digits it generates itself. If that is not desired, the application can disable digit monitoring while generating digits.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_GENERATE, LINEDEVCAPS, lineDial, lineGenerateTone


lineGenerateTone

The lineGenerateTone function generates the specified inband tone over the specified call. Invoking this function with a zero for dwToneMode aborts the tone generation currently in progress on the specified call. Invoking lineGenerateTone or lineGenerateDigits while tone generation is in progress aborts the current tone generation or digit generation and initiates the generation of the newly specified tone or digits.

LONG lineGenerateTone(
  HCALL hCall,
  DWORD dwToneMode,
  DWORD dwDuration,
  DWORD dwNumTones,
  LPLINEGENERATETONE const lpTones
);

Parameters

hCall
A handle to the call on which a tone is to be generated. The application must be an owner of the call. The call state of hCall can be any state.
dwToneMode
Defines the tone to be generated. Tones can be either standard or custom. A custom tone is composed of a set of arbitrary frequencies. A small number of standard tones are predefined. The duration of the tone is specified with dwDuration for both standard and custom tones. The dwToneMode parameter can only have one bit set. If no bits are set (the value 0 is passed), tone generation is canceled. This parameter uses the following LINETONEMODE_ constants:
LINETONEMODE_CUSTOM
The tone is a custom tone, defined by the specified frequencies.
LINETONEMODE_RINGBACK
The tone to be generated is ring tone. The exact ringback tone is service provider defined.
LINETONEMODE_BUSY
The tone is a standard (station) busy tone. The exact busy tone is service provider defined.
LINETONEMODE_BEEP
The tone is a beep, as used to announce the beginning of a recording. The exact beep tone is service provider defined.
LINETONEMODE_BILLING
The tone is a billing information tone such as a credit card prompt tone. The exact billing tone is service provider defined.
dwDuration
Duration in milliseconds during which the tone should be sustained. A value of 0 for dwDuration uses a default duration for the specified tone. Default values are:

CUSTOM: infinite

RINGBACK: infinite

BUSY: infinite

BEEP: infinite

BILLING: fixed (single cycle)

dwNumTones
The number of entries in the lpTones array. This parameter is ignored if dwToneMode is not equal to CUSTOM.
lpTones
A pointer to a LINEGENERATETONE array that specifies the tone's components. This parameter is ignored for non-custom tones. If lpTones is a multifrequency tone, the various tones are played simultaneously.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALTONEMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALTONE, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

The lineGenerateTone function is considered to have completed successfully when the tone generation has been successfully initiated, not when the generation of the tone is finished. The function allows the inband generation of several predefined tones, such as ringback, busy tones, and beep. It also allows for the fabrication of custom tones by specifying their component frequencies, cadence, and volume. Because these tones are generated as inband tones, the call would typically have to be in the connected state for tone generation to be effective. When the generation of the tone is complete, or when tone generation is canceled, a LINE_GENERATE message is sent to the application.

Only one inband generation request (tone generation or digit generation) is allowed to be in progress per call across all applications that are owners of the call. This implies that if tone generation is currently in progress on a call, invoking lineGenerateDigits cancels the tone generation.

If the LINEERR_INVALPOINTER error value is returned, the specified lpTones parameter is invalid or the value specified by the dwNumTones parameter is too large.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_GENERATE, lineGenerateDigits, LINEGENERATETONE


lineGetAddressCaps

The lineGetAddressCaps function queries the specified address on the specified line device to determine its telephony capabilities.

LONG lineGetAddressCaps(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  DWORD dwAddressID,
  DWORD dwAPIVersion,
  DWORD dwExtVersion,
  LPLINEADDRESSCAPS lpAddressCaps
);

Parameters

hLineApp
The handle to the application's registration with TAPI.
dwDeviceID
The line device containing the address to be queried.
dwAddressID
The address on the given line device whose capabilities are to be queried.
dwAPIVersion
The version number of the Telephony API to be used. The high-order word contains the major version number; the low-order word contains the minor version number. This number is obtained by lineNegotiateAPIVersion.
dwExtVersion
The version number of the service provider-specific extensions to be used. This number can be left zero if no device-specific extensions are to be used. Otherwise, the high-order word contains the major version number; and the low-order word contains the minor version number.
lpAddressCaps
A pointer to a variably sized structure of type LINEADDRESSCAPS. Upon successful completion of the request, this structure is filled with address capabilities information. Prior to calling lineGetAddressCaps, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALAPPHANDLE, LINEERR_UNINITIALIZED, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_NODRIVER, LINEERR_NODEVICE.

Remarks

Valid address identifiers range from zero to one less than the number of addresses returned by lineGetDevCaps. The version number to be supplied is the version number that was returned as part of the line's device capabilities by lineGetDevCaps.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINEADDRESSCAPS, lineGetDevCaps, lineNegotiateAPIVersion


lineGetAddressID

The lineGetAddressID function returns the address identifier associated with an address in a different format on the specified line.

LONG lineGetAddressID(
  HLINE hLine,
  LPDWORD lpdwAddressID,
  DWORD dwAddressMode,
  LPCSTR lpsAddress,
  DWORD dwSize
);

Parameters

hLine
A handle to the open line device.
lpdwAddressID
A pointer to a DWORD-sized memory location where the address identifier is returned.
dwAddressMode
The address mode of the address contained in lpsAddress. The dwAddressMode parameter is allowed to have only a single flag set. This parameter uses the following LINEADDRESSMODE_ constants:
LINEADDRESSMODE_DIALABLEADDR
The address is specified by its dialable address. The lpsAddress parameter is the dialable address or canonical address format.
lpsAddress
A pointer to a data structure holding the address assigned to the specified line device. The format of the address is determined by dwAddressMode. Because the only valid value is LINEADDRESSMODE_DIALABLEADDR, lpsAddress uses the common dialable number format and is NULL-terminated.
dwSize
The size of the address contained in lpsAddress.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALADDRESS, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

The lineGetAddressID function is used to map a phone number (address) assigned to a line device back to its dwAddressID in the range zero to the number of addresses minus one returned in the line's device capabilities. The lineMakeCall function allows the application to make a call by specifying a line handle and an address on the line. The address can be specified as a dwAddressID, as a phone number, or as a device-specific name or identifier. Using a phone number can be practical in environments where a single line is assigned multiple addresses.

Note LINEADDRESSMODE_ADDRESSID may not be used with lineGetAddressID.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, lineMakeCall


lineGetAddressStatus

The lineGetAddressStatus function allows an application to query the specified address for its current status.

LONG lineGetAddressStatus(
  HLINE hLine,
  DWORD dwAddressID,
  LPLINEADDRESSSTATUS lpAddressStatus
);

Parameters

hLine
A handle to the open line device.
dwAddressID
An address on the given open line device. This is the address to be queried.
lpAddressStatus
A pointer to a variably sized data structure of type LINEADDRESSSTATUS. Prior to calling lineGetAddressStatus, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_OPERATIONUNAVAIL, LINEERR_OPERATIONFAILED.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINEADDRESSSTATUS


lineGetAgentActivityList

The lineGetAgentActivityList function obtains the identities of activities that the application can select using lineSetAgentActivity to indicate what function the agent is actually performing at the moment.

LONG lineGetAgentActivityList(
  HLINE hLine,
  DWORD dwAddressID,
  LPLINEAGENTACTIVITYLIST lpAgentActivityList
);

Parameters

hLine
A handle to the open line device.
dwAddressID
The address on the open line device whose agent status is to be queried.
lpAgentAcvitityList
A pointer to a variably sized structure of type LINEAGENTACTIVITYLIST. Upon successful completion of the request, this structure is filled with a list of the agent activity codes that can be selected using lineSetAgentActivity. Prior to calling lineGetAgentActivityList, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, this function returns one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALAGENTID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINEAGENTACTIVITYLIST, lineSetAgentActivity


lineGetAgentCaps

The lineGetAgentCaps function obtains the agent-related capabilities supported on the specified line device. If a specific agent is named, the capabilities include a listing of ACD groups into which the agent is permitted to log in.

LONG lineGetAgentCaps(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  DWORD dwAddressID,
  DWORD dwAppAPIVersion,
  LPLINEAGENTCAPS lpAgentCaps
);

Parameters

hLineApp
The handle to the application's registration with TAPI.
dwDeviceID
The line device containing the address to be queried.
dwAddressID
The address on the given line device whose capabilities are to be queried.
dwAppAPIVersion
The highest API version supported by the application. This should not be the value negotiated using lineNegotiateAPIVersion on the device being queried.
lpAgentCaps
A pointer to a variably sized structure of type LINEAGENTCAPS. Upon successful completion of the request, this structure is filled with agent capabilities information. Prior to calling lineGetAgentCaps, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, this function returns one of these negative error values:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NODRIVER, LINEERR_UNINITIALIZED, LINEERR_NODEVICE.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINEAGENTCAPS, lineNegotiateAPIVersion


lineGetAgentGroupList

The lineGetAgentGroupList function obtains the identities of agent groups (combination of queue, supervisor, skill level, and so on) into which the agent currently logged in on the workstation is permitted to log into on the automatic call distributor.

LONG lineGetAgentGroupList(
  HLINE hLine,
  DWORD dwAddressID,
  LPLINEAGENTGROUPLIST lpAgentGroupList
);

Parameters

hLine
A handle to the open line device.
dwAddressID
The address on the open line device whose agent status is to be queried.
lpAgentGroupList
A pointer to a variably sized structure of type LINEAGENTGROUPLIST. Upon successful completion of the request, this structure is filled with a list of the agent groups into which the agent can log in at this time (which should include any groups into which the agent is already logged in, if any). Prior to calling lineGetAgentGroupList, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, this function returns one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_INVALAGENTID, LINEERR_INVALLINEHANDLE, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_UNINITIALIZED.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINEAGENTGROUPLIST


lineGetAgentStatus

The lineGetAgentStatus function obtains the agent-related status on the specified address.

LONG lineGetAgentStatus(
  HLINE hLine,
  DWORD dwAddressID,
  LPLINEAGENTSTATUS lpAgentStatus
);

Parameters

hLine
A handle to the open line device.
dwAddressID
The address on the open line device whose agent status is to be queried.
lpAgentStatus
A pointer to a variably sized structure of type LINEAGENTSTATUS. Upon successful completion of the request, this structure is filled with agent status information. Prior to calling lineGetAgentStatus, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_INVALLINEHANDLE, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_UNINITIALIZED.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINEAGENTSTATUS


lineGetAppPriority

The lineGetAppPriority function allows an application to determine whether or not it is in the handoff priority list for a particular media mode or Assisted Telephony request mode and, if so, its position in the priority list.

LONG lineGetAppPriority(
  LPCSTR lpszAppFilename,
  DWORD dwMediaMode,
  LPLINEEXTENSIONID const lpExtensionID,
  DWORD dwRequestMode,
  LPVARSTRING lpExtensionName,
  LPDWORD lpdwPriority
);

Parameters

lpszAppFilename
A pointer to a string containing the application executable module filename (without directory information). In API version 2.0 or later, the parameter can be in either long or 8.3 filename format. In API versions earlier than 2.0, the parameter must specify a filename in the 8.3 format; long filenames cannot be used.
dwMediaMode
The media mode for which the priority information is to be obtained. The value can be one of the LINEMEDIAMODE_ constants; only a single bit can be on. The value 0 should be used if checking application priority for Assisted Telephony requests.
lpExtensionID
A pointer to structure of type LINEEXTENSIONID. This parameter is ignored.
dwRequestMode
If the dwMediaMode parameter is zero, this parameter specifies the Assisted Telephony request mode for which priority is to be checked. It must be either LINEREQUESTMODE_MAKECALL or LINEREQUESTMODE_MEDIACALL. This parameter is ignored if dwMediaMode is non-zero.
lpExtensionName
This parameter is ignored.
lpdwPriority
A pointer to a DWORD-size memory location into which TAPI writes the priority of the application for the specified media or request mode. The value 0 is returned if the application is not in the stored priority list and does not currently have any line device open with ownership requested of the specified media mode or having registered for the specified request mode.

In API versions earlier than 2.0, the value –1 (0xFFFFFFFF) is returned if the application has the line open for the specified media mode or has registered for the specified requests, but the application is not in the stored priority list (that is, it is in the temporary priority list only). In API version 2.0 or later, the value 0 is returned to indicate this condition.

Otherwise, the value indicates the application's position in the list (with 1 being highest priority, and increasing values indicating decreasing priority).

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_INVALREQUESTMODE, LINEERR_INVALAPPNAME, LINEERR_NOMEM, LINEERR_INVALMEDIAMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL.

Remarks

If LINEERR_INVALMEDIAMODE is returned, the value specified in dwMediaMode is not zero, not a valid extended media mode, and not a LINEMEDIAMODE_ constant, or more than one bit is on in the parameter value.

Also, long filenames are now permitted for lpszAppFilename; 8.3 format names are acceptable, but no longer required.

Although this is a new function that older applications would not be expected to call, for backward compatibility they should not be prevented from doing so; the function works the same way for all applications.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINEEXTENSIONID, VARSTRING


lineGetCallInfo

The lineGetCallInfo function enables an application to obtain fixed information about the specified call.

LONG lineGetCallInfo(
  HCALL hCall,
  LPLINECALLINFO lpCallInfo
);

Parameters

hCall
A handle to the call to be queried. The call state of hCall can be any state.
lpCallInfo
A pointer to a variably sized data structure of type LINECALLINFO. Upon successful completion of the request, this structure is filled with call-related information. Prior to calling lineGetCallInfo, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL.

Remarks

A separate LINECALLINFO structure exists for every incoming or outgoing call. The structure contains primarily fixed information about the call. An application would typically be interested in checking this information when it receives its handle for a call by the LINE_CALLSTATE message, or each time it receives notification by a LINE_CALLINFO message that parts of the call information structure have changed. These messages supply the handle for the call as a parameter.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINE_CALLINFO, LINE_CALLSTATE, LINECALLINFO


lineGetCallStatus

The lineGetCallStatus function returns the current status of the specified call.

LONG lineGetCallStatus(
  HCALL hCall,
  LPLINECALLSTATUS lpCallStatus
);

Parameters

hCall
A handle to the call to be queried. The call state of hCall can be any state.
lpCallStatus
A pointer to a variably sized data structure of type LINECALLSTATUS. Upon successful completion of the request, this structure is filled with call status information. Prior to calling lineGetCallStatus, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL.

Remarks

The lineGetCallStatus function returns the dynamic status of a call, whereas lineGetCallInfo returns primarily static information about a call. Call status information includes the current call state, detailed mode information related to the call while in this state (if any), as well as a list of the available API functions the application can invoke on the call while the call is in this state. An application would typically be interested in requesting this information when it receives notification about a call state change by the LINE_CALLSTATE message.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINE_CALLSTATE, LINECALLSTATUS, lineGetCallInfo


lineGetConfRelatedCalls

The lineGetConfRelatedCalls function returns a list of call handles that are part of the same conference call as the specified call. The specified call is either a conference call or a participant call in a conference call. New handles are generated for those calls for which the application does not already have handles, and the application is granted monitor privilege to those calls.

LONG lineGetConfRelatedCalls(
  HCALL hCall,
  LPLINECALLLIST lpCallList
);

Parameters

hCall
A handle to a call. This is either a conference call or a participant call in a conference call. For a conference parent call, the call state of hCall can be any state. For a conference participant call, it must be in the conferenced state.
lpCallList
A pointer to a variably sized data structure of type LINECALLLIST. Upon successful completion of the request, call handles to all calls in the conference call are returned in this structure. The first call in the list is the conference call, the other calls are the participant calls. The application is granted monitor privilege to those calls for which it does not already have handles; the privileges to calls in the list for which the application already has handles is unchanged. Prior to calling lineGetConfRelatedCalls, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOCONFERENCE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

The specified call can either be a conference call handle or a handle to a participant call. For example, a consultation call that has not yet been added to a conference call is not part of a conference. The first entry in the list that is returned is the conference call handle, the other handles are all the participant calls. The specified call is always one of the calls returned in the list. Calls in the list to which the application does not already have a call handle are assigned monitor privilege; privileges to calls for which the application already has handles are unchanged. The application can use lineSetCallPrivilege to change the privilege of the call.

If lineGetConfRelatedCalls is called immediately after a call is added to a conference using lineCompleteTransfer, lineGetConfRelatedCalls may not return a complete list of related calls because TAPI waits to receive a LINE_CALLSTATE message indicating that the call has entered LINECALLSTATE_CONFERENCED before it considers the call to actually be part of the conference (that is, the conferenced state is confirmed by the service provider). After the application has received the LINE_CALLSTATE message, lineGetConfRelatedCalls returns complete information.

The application can invoke lineGetCallInfo and lineGetCallStatus for each call in the list to determine the call's information and status, respectively.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINE_CALLSTATE, lineCompleteTransfer, lineGetCallInfo, lineGetCallStatus, lineSetCallPrivilege


lineGetCountry

The lineGetCountry function fetches the stored dialing rules and other information related to a specified country, the first country in the country list, or all countries.

LONG lineGetCountry(
  DWORD dwCountryID,
  DWORD dwAPIVersion,
  LPLINECOUNTRYLIST lpLineCountryList
);

Parameters

dwCountryID
The country identifier (not the country code) of the country for which information is to be obtained. If the value 1 is specified, information on the first country in the country list is obtained. If the value 0 is specified, information on all countries is obtained (which can require a great deal of memory—20 KB or more).
dwAPIVersion
The highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on some particular line device).
lpLineCountryList
A pointer to a location to which a LINECOUNTRYLIST structure is loaded. Prior to calling lineGetCountry, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INIFILECORRUPT, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER.

Remarks

Although this is a new function that older applications would not be expected to call, for backward compatibility they should not be prevented from doing so. The function works the same way for all applications.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINECOUNTRYLIST, lineNegotiateAPIVersion


lineGetDevCaps

The lineGetDevCaps function queries a specified line device to determine its telephony capabilities. The returned information is valid for all addresses on the line device.

LONG lineGetDevCaps(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  DWORD dwAPIVersion,
  DWORD dwExtVersion,
  LPLINEDEVCAPS lpLineDevCaps
);

Parameters

hLineApp
The handle to the application's registration with TAPI.
dwDeviceID
The line device to be queried.
dwAPIVersion
The version number of the Telephony API to be used. The high-order word contains the major version number; the low-order word contains the minor version number. This number is obtained by lineNegotiateAPIVersion.
dwExtVersion
The version number of the service provider-specific extensions to be used. This number is obtained by lineNegotiateExtVersion. It can be left zero if no device-specific extensions are to be used. Otherwise, the high-order word contains the major version number; the low-order word contains the minor version number.
lpLineDevCaps
A pointer to a variably sized structure of type LINEDEVCAPS. Upon successful completion of the request, this structure is filled with line device capabilities information. Prior to calling lineGetDevCaps, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALAPPHANDLE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NODEVICE.

Remarks

Before using lineGetDevCaps, the application must negotiate the API version number to use, and, if desired, the extension version to use.

The API and extension version numbers are those under which TAPI and the service provider must operate. If version ranges do not overlap, the application, API, or service-provider versions are incompatible and an error is returned.

One of the members in the LINEDEVCAPS structure returned by this function contains the number of addresses assigned to the specified line device. The actual address identifiers used to reference individual addresses vary from zero to one less than the returned number. The capabilities of each address can be different. Use lineGetAddressCaps for each available <dwDeviceID, dwAddressID> combination to determine the exact capabilities of each address.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINEDEVCAPS, lineGetAddressCaps, lineNegotiateAPIVersion, lineNegotiateExtVersion


lineGetDevConfig

The lineGetDevConfig function returns an "opaque" data structure object, the contents of which are specific to the line (service provider) and device class. The data structure object stores the current configuration of a media-stream device associated with the line device.

LONG lineGetDevConfig(
  DWORD dwDeviceID,
  LPVARSTRING lpDeviceConfig,
  LPCSTR lpszDeviceClass
);

Parameters

dwDeviceID
The line device to be configured.
lpDeviceConfig
A pointer to the memory location of type VARSTRING where the device configuration structure is returned. Upon successful completion of the request, this location is filled with the device configuration. The dwStringFormat member in the VARSTRING structure is set to STRINGFORMAT_BINARY. Prior to calling lineGetDevConfig, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.
lpszDeviceClass
A pointer to a NULL-terminated ASCII string that specifies the device class of the device whose configuration is requested. Valid device class lineGetID strings are the same as those specified for the function.

Return Values

Returns zero if the function succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NODEVICE.

Remarks

Call states are device specific.

The lineGetDevConfig function can be used to retrieve a data structure from TAPI that specifies the configuration of a media stream device associated with a particular line device. For example, the contents of this structure could specify data rate, character format, modulation schemes, and error control protocol settings for a "datamodem" media device associated with the line.

Typically, an application calls lineGetID to identify the media stream device associated with a line, and then calls lineConfigDialog to allow the user to set up the device configuration. It could then call lineGetDevConfig, and save the configuration information in a phone book (or other database) associated with a particular call destination. When the user later wishes to call the same destination again, lineSetDevConfig can be used to restore the configuration settings selected by the user. The functions lineSetDevConfig, lineConfigDialog, and lineGetDevConfig can be used, in that order, to allow the user to view and update the settings.

The exact format of the data contained within the structure is specific to the line and media stream API (device class), is undocumented, and is undefined. The structure returned by this function cannot be directly accessed or manipulated by the application, but can only be stored intact and later used in lineSetDevConfig to restore the settings. The structure also cannot necessarily be passed to other devices, even of the same device class (although this can work in some instances, it is not guaranteed).

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, lineConfigDialog, lineGetID, lineSetDevConfig, VARSTRING


lineGetIcon

The lineGetIcon function allows an application to retrieve a service line device-specific (or provider-specific) icon for display to the user.

LONG lineGetIcon(
  DWORD dwDeviceID,
  LPCSTR lpszDeviceClass,
  LPHICON lphIcon
);

Parameters

dwDeviceID
The line device whose icon is requested.
lpszDeviceClass
A pointer to a NULL-terminated string that identifies a device class name. This device class allows the application to select a specific sub-icon applicable to that device class. This parameter is optional and can be left NULL or empty, in which case the highest-level icon associated with the line device rather than a specified media stream device would be selected.
lphIcon
A pointer to a memory location in which the handle to the icon is returned.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALDEVICECLASS, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_NODEVICE.

Remarks

The lineGetIcon function causes the provider to return a handle (in lphIcon) to an icon resource (obtained from LoadIcon) that is associated with the specified line. The icon handle is for a resource associated with the provider. The application must use CopyIcon if it wants to reference the icon after the provider is unloaded, which is unlikely to happen as long as the application has the line open.

The lpszDeviceClass parameter allows the provider to return different icons based on the type of service being referenced by the caller. The permitted strings are the same as for lineGetID. For example, if the line supports the Comm API, passing "COMM" as lpszDeviceClass causes the provider to return an icon related specifically to the Comm device functions of the service provider. The parameters "tapi/line", "", or NULL can be used to request the icon for the line service.

For applications using an API version earlier than 2.0, if the provider does not return an icon (whether because the given device class is invalid or the provider does not support icons), TAPI substitutes a generic Win32 Telephony line device icon. For applications using API version 2.0 or later, TAPI substitutes the default line icon only if the lpszDeviceClass parameter is "tapi/line", "" or NULL. For any other device class, if the given device class is not valid or the provider does not support icons for the class, lineGetIcon returns LINEERR_INVALDEVICECLASS.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, lineGetID


lineGetID

The lineGetID function returns a device identifier for the specified device class associated with the selected line, address, or call.

LONG lineGetID(
  HLINE hLine,
  DWORD dwAddressID,
  HCALL hCall,
  DWORD dwSelect,
  LPVARSTRING lpDeviceID,
  LPCSTR lpszDeviceClass
);

Parameters

hLine
A handle to an open line device.
dwAddressID
An address on the given open line device.
hCall
A handle to a call.
dwSelect
Specifies whether the requested device identifier is associated with the line, address or a single call. The dwSelect parameter can only have a single flag set. This parameter uses the following LINECALLSELECT_ constants:
LINECALLSELECT_LINE
Selects the specified line device. The hLine parameter must be a valid line handle; hCall and dwAddressID are ignored.
LINECALLSELECT_ADDRESS
Selects the specified address on the line. Both hLine and dwAddressID must be valid; hCall is ignored.
LINECALLSELECT_CALL
Selects the specified call. hCall must be valid; hLine and dwAddressID are both ignored.
lpDeviceID
A pointer to a memory location of type VARSTRING, where the device identifier is returned. Upon successful completion of the request, this location is filled with the device identifier. The format of the returned information depends on the method used by the device class API for naming devices. Prior to calling lineGetID, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.
lpszDeviceClass
A pointer to a NULL-terminated ASCII string that specifies the device class of the device whose identifier is requested. Valid device class strings are those used in the SYSTEM.INI section to identify device classes.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSELECT, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NODEVICE, LINEERR_UNINITIALIZED.

Remarks

The lineGetID function can be used to retrieve a line-device identifier when given a line handle. This is useful after a line device has been opened using LINEMAPPER as a device identifier in order to determine the real line-device identifier of the opened line. This function can also be used to obtain the device identifier of a phone device or media device (for device classes such as COM, wave, MIDI, phone, line, or NDIS) associated with a call, address or line. This identifier can then be used with the appropriate API (such as phone, MIDI, wave) to select the corresponding media device associated with the specified call.

See Device Classes in TAPI for device class names.

A vendor that defines a device-specific media mode also needs to define the corresponding device-specific (proprietary) API to manage devices of the media mode. To avoid collisions on device class names assigned independently by different vendors, a vendor should select a name that uniquely identifies both the vendor and, following it, the media type. For example: "intel/video".

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, VARSTRING


lineGetLineDevStatus

The lineGetLineDevStatus function enables an application to query the specified open line device for its current status.

LONG lineGetLineDevStatus(
  HLINE hLine,
  LPLINEDEVSTATUS lpLineDevStatus
);

Parameters

hLine
A handle to the open line device to be queried.
lpLineDevStatus
A pointer to a variably sized data structure of type LINEDEVSTATUS. Upon successful completion of the request, this structure is filled with the line's device status. Prior to calling lineGetLineDevStatus, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL.

Remarks

An application uses lineGetLineDevStatus to query the line device for its current line status. This status information applies globally to all addresses on the line device. Use lineGetAddressStatus to determine status information about a specific address on a line.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINEDEVSTATUS, lineGetAddressStatus


lineGetMessage

The lineGetMessage function returns the next TAPI message that is queued for delivery to an application that is using the Event Handle notification mechanism (see lineInitializeEx for further details).

LONG lineGetMessage(
  HLINEAPP hLineApp,
  LPLINEMESSAGE lpMessage,
  DWORD dwTimeout
);

Parameters

hLineApp
The handle returned by lineInitializeEx. The application must have set the LINEINITIALIZEEXOPTION_USEEVENT option in the dwOptions member of the LINEINITIALIZEEXPARAMS structure.
lpMessage
A pointer to a LINEMESSAGE structure. Upon successful return from this function, the structure contains the next message that had been queued for delivery to the application.
dwTimeout
The time-out interval, in milliseconds. The function returns if the interval elapses, even if no message can be returned. If dwTimeout is zero, the function checks for a queued message and returns immediately. If dwTimeout is INFINITE, the function's time-out interval never elapses.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALAPPHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_NOMEM.

Remarks

If the lineGetMessage function has been called with a non-zero timeout and the application calls lineShutdown on another thread, this function returns immediately with LINEERR_INVALAPPHANDLE.

If the timeout expires (or was zero) and no message could be fetched from the queue, the function returns with the error LINEERR_OPERATIONFAILED.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

lineInitializeEx, LINEINITIALIZEEXPARAMS, LINEMESSAGE, lineShutdown


lineGetNewCalls

The lineGetNewCalls function returns call handles to calls on a specified line or address for which the application currently does not have handles. The application is granted monitor privilege to these calls.

LONG lineGetNewCalls(
  HLINE hLine,
  DWORD dwAddressID,
  DWORD dwSelect,
  LPLINECALLLIST lpCallList
);

Parameters

hLine
A handle to an open line device.
dwAddressID
An address on the given open line device.
dwSelect
The selection of calls that are requested. Note that dwSelect can only have one bit set. This parameter uses the following LINECALLSELECT_ constants:
LINECALLSELECT_LINE
Selects calls on the specified line device. The hLine parameter must be a valid line handle; dwAddressID is ignored.
LINECALLSELECT_ADDRESS
Selects calls on the specified address on the specified line device. Both hLine and dwAddressID must be valid.
lpCallList
A pointer to a variably sized data structure of type LINECALLLIST. Upon successful completion of the request, call handles to all selected calls are returned in this structure. Prior to calling lineGetNewCalls, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSELECT, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

An application can use lineGetNewCalls to obtain handles to calls for which it currently has no handles. The application can select the calls for which handles are to be returned by basing this selection on scope (calls on a specified line, or calls on a specified address). For example, an application can request call handles to all calls on a given address for which it currently has no handle. The application is always given monitor privilege to the new call handles. Also, when opening a line, an application uses this function to become aware of existing calls.

The application can invoke lineGetCallInfo and lineGetCallStatus for each call in the list to determine the call's information and status, respectively. It can use lineSetCallPrivilege to change its privilege to owner.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINECALLLIST, lineGetCallInfo, lineGetCallStatus, lineSetCallPrivilege


lineGetNumRings

The lineGetNumRings function determines the number of rings an incoming call on the given address should ring prior to answering the call.

LONG lineGetNumRings(
  HLINE hLine,
  DWORD dwAddressID,
  LPDWORD lpdwNumRings
);

Parameters

hLine
A handle to the open line device.
dwAddressID
An address on the line device.
lpdwNumRings
The number of rings that is the minimum of all current lineSetNumRings requests.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

The lineGetNumRings and lineSetNumRings functions, when used in combination, provide a mechanism to support the implementation of toll-saver features across multiple independent applications.

An application that receives a handle for a call in the offering state and a LINE_LINEDEVSTATE ringing message should wait a number of rings equal to the number returned by lineGetNumRings before answering the call in order to honor the toll-saver settings across all applications. The lineGetNumRings function returns the minimum of all applications' number of rings specified by lineSetNumRings. Because this number can vary dynamically, an application should invoke lineGetNumRings each time it has the option to answer a call. If no application has called lineSetNumRings, the number of rings returned is 0xFFFFFFFF. A separate LINE_LINEDEVSTATE ringing message is sent to the application for each ring cycle.

If call classification is performed by TAPI of answering all calls of unknown media mode and filtering the media stream, TAPI honors this number as well.

Note This operation is purely informational and does not in itself affect the state of any calls on the line device.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINE_LINEDEVSTATE, lineSetNumRings


lineGetProviderList

The lineGetProviderList function returns a list of service providers currently installed in the telephony system.

LONG lineGetProviderList(
  DWORD dwAPIVersion,
  LPLINEPROVIDERLIST lpProviderList
);

Parameters

dwAPIVersion
The highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on some particular line device).
lpProviderList
A pointer to a memory location where TAPI can return a LINEPROVIDERLIST structure. Prior to calling lineGetProviderList, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INIFILECORRUPT, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL.

Remarks

Although this is a new function that older applications would not be expected to call, for backward compatibility they should not be prevented from doing so. The function works the same way for all applications.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, lineNegotiateAPIVersion, LINEPROVIDERLIST


lineGetRequest

The lineGetRequest function retrieves the next by-proxy request for the specified request mode.

LONG lineGetRequest(
  HLINEAPP hLineApp,
  DWORD dwRequestMode,
  LPVOID lpRequestBuffer
);

Parameters

hLineApp
The application's usage handle for the line portion of TAPI.
dwRequestMode
The type of request that is to be obtained. Note that dwRequestMode can only have one bit set. This parameter uses the following LINEREQUESTMODE_ constants:
LINEREQUESTMODE_MAKECALL
A tapiRequestMakeCall request.
lpRequestBuffer
A pointer to a memory buffer where the parameters of the request are to be placed. The size of the buffer and the interpretation of the information placed in the buffer depends on the request mode. The application-allocated buffer is assumed to be of sufficient size to hold the request.

If dwRequestMode is LINEREQUESTMODE_MAKECALL, interpret the content of the request buffer using the LINEREQMAKECALL structure.

If dwRequestMode is LINEREQUESTMODE_MEDIACALL, interpret the content of the request buffer using the LINEREQMEDIACALL structure.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALAPPHANDLE, LINEERR_NOTREGISTERED, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALREQUESTMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NOREQUEST.

Remarks

A telephony-enabled application can request that a call be placed on its behalf by invoking tapiRequestMakeCall. These requests are queued by TAPI and the highest priority application that has registered to handle the request is sent a LINE_REQUEST message with indication of the mode of the request that is pending. Typically, this application is the user's call-control application. The LINE_REQUEST message indicates that zero or more requests may be pending for the registered application to process; after receiving LINE_REQUEST, it is the responsibility of the recipient application to call lineGetRequest until LINEERR_NOREQUEST is returned, indicating that no more requests are pending.

Next, the call-control application that receives this message invokes lineGetRequest, specifying the request mode and a buffer that is large enough to hold the request. The call-control application then interprets and executes the request.

After execution of lineGetRequest, TAPI purges the request from its internal queue, making room available for a subsequent request. It is therefore possible for a new LINE_REQUEST message to be received immediately upon execution of lineGetRequest, should the same or another application issue another request. It is the responsibility of the request recipient application to handle this scenario by some mechanism (for example, by making note of the additional LINE_REQUEST and deferring a subsequent lineGetRequest until processing of the preceding request completes, by getting the subsequent request and buffer as necessary, or by another appropriate means).

The subsequent LINE_REQUEST should not be ignored because it is not repeated by TAPI.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINE_REQUEST, LINEREQMAKECALL, tapiRequestMakeCall


lineGetStatusMessages

The lineGetStatusMessages function enables an application to query which notification messages the application is set up to receive for events related to status changes for the specified line or any of its addresses.

LONG lineGetStatusMessages(
  HLINE hLine,
  LPDWORD lpdwLineStates,
  LPDWORD lpdwAddressStates
);

Parameters

hLine
A handle to the line device.
lpdwLineStates
A bit array that identifies for which line device status changes a message is to be sent to the application. If a flag is TRUE, that message is enabled; if FALSE, it is disabled. Note that multiple flags can be set. This parameter uses the following LINEDEVSTATE_ constants:
LINEDEVSTATE_OTHER
Device-status items other than those listed below have changed. The application should check the current device status to determine which items have changed.
LINEDEVSTATE_RINGING
The switch tells the line to alert the user. Service providers notify applications on each ring cycle by sending LINE_LINEDEVSTATE messages containing this constant. For example, in the United States, service providers send a message with this constant every six seconds.
LINEDEVSTATE_CONNECTED
The line was previously disconnected and is now connected to TAPI.
LINEDEVSTATE_NUMCOMPLETIONS
The number of outstanding call completions on the line device has changed.
LINEDEVSTATE_DISCONNECTED
This line was previously connected and is now disconnected from TAPI.
LINEDEVSTATE_MSGWAITON
The "message waiting" indicator is turned on.
LINEDEVSTATE_MSGWAITOFF
The "message waiting" indicator is turned off.
LINEDEVSTATE_INSERVICE
The line is connected to TAPI. This happens when TAPI is first activated or when the line wire is physically plugged in and in service at the switch while TAPI is active.
LINEDEVSTATE_OUTOFSERVICE
The line is out of service at the switch or physically disconnected. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_MAINTENANCE
Maintenance is being performed on the line at the switch. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_OPEN
The line has been opened by some application.
LINEDEVSTATE_CLOSE
The line has been closed by some application.
LINEDEVSTATE_NUMCALLS
The number of calls on the line device has changed.
LINEDEVSTATE_TERMINALS
The terminal settings have changed.
LINEDEVSTATE_ROAMMODE
The roam mode of the line device has changed.
LINEDEVSTATE_BATTERY
The battery level has changed significantly (cellular).
LINEDEVSTATE_SIGNAL
The signal level has changed significantly (cellular).
LINEDEVSTATE_DEVSPECIFIC
The line's device-specific information has changed.
LINEDEVSTATE_REINIT
Items have changed in the configuration of line devices. To become aware of these changes (for example, the appearance of new line devices) the application should reinitialize its use of TAPI. The hDevice parameter of the LINE_LINEDEVSTATE message is left NULL for this state change as it applies to any of the lines in the system.
LINEDEVSTATE_LOCK
The locked status of the line device has changed.
LINEDEVSTATE_REMOVED
The device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). Normally, a LINE_LINEDEVSTATE message with this value is immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version does not receive any notification.
lpdwAddressStates
A bit array that identifies for which address status changes a message is to be sent to the application. If a flag is TRUE, that message is enabled; if FALSE, disabled. Multiple flags can be set. This parameter uses the following LINEADDRESSSTATE_ constants:
LINEADDRESSSTATE_OTHER
Address-status items other than those listed below have changed. The application should check the current address status to determine which items have changed.
LINEADDRESSSTATE_DEVSPECIFIC
The device-specific item of the address status has changed.
LINEADDRESSSTATE_INUSEZERO
The address has changed to idle (it is now in use by zero stations).
LINEADDRESSSTATE_INUSEONE
The address has changed from being idle or from being in use by many bridged stations to being in use by just one station.
LINEADDRESSSTATE_INUSEMANY
The monitored or bridged address has changed from being in use by one station to being used by more than one station.
LINEADDRESSSTATE_NUMCALLS
The number of calls on the address has changed. This is the result of events such as a new incoming call, an outgoing call on the address, or a call changing its hold status.
LINEADDRESSSTATE_FORWARD
The forwarding status of the address has changed, including the number of rings for determining a "no answer" condition. The application should check the address status to determine details about the address's current forwarding status.
LINEADDRESSSTATE_TERMINALS
The terminal settings for the address have changed.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

TAPI defines a number of messages that notify applications about events occurring on lines and addresses. An application may not be interested in receiving all address and line status change messages. The lineSetStatusMessages function can be used to select which messages the application wants to receive. By default, address status and line status reporting is disabled.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINE_CLOSE, LINE_LINEDEVSTATE, lineSetStatusMessages


lineGetTranslateCaps

The lineGetTranslateCaps function returns address translation capabilities.

LONG lineGetTranslateCaps(
  HLINEAPP hLineApp,
  DWORD dwAPIVersion,
  LPLINETRANSLATECAPS lpTranslateCaps
);

Parameters

hLineApp
The application handle returned by lineInitializeEx. If an application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL.
dwAPIVersion
The highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on some particular line device).
lpTranslateCaps
A pointer to a location to which a LINETRANSLATECAPS structure is loaded. Prior to calling lineGetTranslateCaps, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INIFILECORRUPT, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NODRIVER.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, lineInitializeEx, lineNegotiateAPIVersion, LINETRANSLATECAPS


lineHandoff

The lineHandoff function gives ownership of the specified call to another application. The application can be either specified directly by its filename or indirectly as the highest priority application that handles calls of the specified media mode.

LONG lineHandoff(
  HCALL hCall,
  LPCSTR lpszFileName,
  DWORD dwMediaMode
);

Parameters

hCall
A handle to the call to be handed off. The application must be an owner of the call. The call state of hCall can be any state.
lpszFileName
A pointer to a NULL-terminated ASCII string. If this pointer parameter is non-NULL, it contains the filename of the application that is the target of the handoff. If NULL, the handoff target is the highest priority application that has opened the line for owner privilege for the specified media mode. A valid filename does not include the path of the file.
dwMediaMode
The media mode used to identify the target for the indirect handoff. The dwMediaMode parameter indirectly identifies the target application that is to receive ownership of the call. This parameter is ignored if lpszFileName is not NULL. Only a single flag can be set in the dwMediaMode parameter at any one time. This parameter uses the following LINEMEDIAMODE_ constants:
LINEMEDIAMODE_UNKNOWN
The target application is the one that handles calls of unknown media mode (unclassified calls).
LINEMEDIAMODE_INTERACTIVEVOICE
The target application is the one that handles calls with the interactive voice media mode (live conversations).
LINEMEDIAMODE_AUTOMATEDVOICE
Voice energy is present on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM
The target application is the one that handles calls with the data modem media mode.
LINEMEDIAMODE_G3FAX
The target application is the one that handles calls with the group 3 fax media mode.
LINEMEDIAMODE_TDD
The target application is the one that handles calls with the TDD (Telephony Devices for the Deaf) media mode.
LINEMEDIAMODE_G4FAX
The target application is the one that handles calls with the group 4 fax media mode.
LINEMEDIAMODE_DIGITALDATA
The target application is the one that handles calls that are digital data calls.
LINEMEDIAMODE_TELETEX
The target application is the one that handles calls with the teletex media mode.
LINEMEDIAMODE_VIDEOTEX
The target application is the one that handles calls with the videotex media mode.
LINEMEDIAMODE_TELEX
The target application is the one that handles calls with the telex media mode.
LINEMEDIAMODE_MIXED
The target application is the one that handles calls with the ISDN mixed media mode.
LINEMEDIAMODE_ADSI
The target application is the one that handles calls with the ADSI (Analog Display Services Interface) media mode.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_TARGETNOTFOUND, LINEERR_INVALPOINTER, LINEERR_TARGETSELF, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NOTOWNER.

Remarks

The lineHandoff function returns LINEERR_TARGETSELF if the calling application attempted an indirect handoff (that is, set the lpszFileName parameter to NULL) and TAPI determined that the application is itself the highest priority application for the given media mode. If LINEERR_TARGETNOTFOUND is returned, a target for the call handoff was not found. This can occur if the named application did not open the same line with the LINECALLPRIVILEGE_OWNER bit in the dwPrivileges parameter of lineOpen. Or, in the case of media-mode handoff, no application has opened the same line with the LINECALLPRIVILEGE_OWNER bit in the dwPrivileges parameter of lineOpen and with the media mode specified in the dwMediaModes parameter of lineOpen.

Call handoff allows ownership of a call to be passed among applications. There are two types of handoff. In the first type, if the application knows the filename of the target application, it can simply specify that filename. If an instance of the target application has opened the line device, ownership of the call is passed to the other application; otherwise, the handoff fails and an error is returned. This form of handoff succeeds if the call handle is handed off to the same filename as the application requesting the handoff.

The second type of handoff is based on media mode. In this case, the application indirectly specifies the target application by means of a media mode. The highest priority application that has currently opened the line device for that media mode is the target for the handoff. If there is no such application, the handoff fails and an error is returned.

The lineHandoff function does not change the media mode of a call. To change the media mode of a call, the application should use lineSetMediaMode on the call, specifying the new media mode. This changes the call's media mode as stored in the call's LINECALLINFO structure.

If handoff succeeds, the receiving application receives a LINE_CALLSTATE message for the call. This message indicates that the receiving application has owner privilege to the call (dwParam3). In addition, the number of owners and/or monitors for the call may have changed. This is reported by the LINE_CALLINFO message, and the receiving application can then invoke lineGetCallStatus and lineGetCallInfo to retrieve more information about the received call.

The receiving application should first check the media mode in LINECALLINFO. If only a single media mode flag is set, the call is officially of that media mode, and the application can act accordingly. If UNKNOWN and other media mode flags are set, then the media mode of the call is officially UNKNOWN but is assumed to be of one of the media modes for which a flag is set in LINECALLINFO. The application should assume that it ought to probe for the highest priority media mode.

If the probe succeeds (either for that media mode or for another one), the application should set the media mode member in LINECALLINFO to the single media mode that was recognized. If the media mode flag matches the LINECALLINFO media mode, the application can act accordingly. If it makes a determination for another media mode, it must first hand off the call to that media mode.

If the probe fails, the application should clear the corresponding media mode flag in LINECALLINFO and hand off the call, specifying dwMediaMode as LINEMEDIAMODE_UNKNOWN. It should also deallocate its call handle (or revert back to monitoring).

If none of the media modes succeeded in making a determination, only the UNKNOWN flag remains set in the media mode field of LINECALLINFO at the time the media application attempts to hand off the call to UNKNOWN. The final lineHandoff fails if the application is the only remaining owner of the call. This informs the application that it should drop the call and deallocate its handle, in which case the call is abandoned. The privileges of the invoking application to the call are unchanged by this operation, but the application can change its privileges to a call with lineSetCallPrivilege.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINECALLINFO, lineGetCallStatus, lineOpen, lineSetCallPrivilege, lineSetMediaMode


lineHold

The lineHold function places the specified call on hold.

LONG lineHold(
  HCALL hCall
);

Parameters

hCall
A handle to the call to be placed on hold. The application must be an owner of the call. The call state of hCall must be connected.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED.

Remarks

The call on hold is temporarily disconnected allowing the application to use the line device for making or answering other calls. The lineHold function performs a so-called "hard hold" of the specified call (as opposed to a "consultation call"). A call on hard hold typically cannot be transferred or included in a conference call, but a consultation call can. Consultation calls are initiated using lineSetupTransfer, lineSetupConference, or linePrepareAddToConference.

After a call has been successfully placed on hold, the call state typically transitions to onHold. A held call is retrieved by lineUnhold. While a call is on hold, the application can receive LINE_CALLSTATE messages about state changes of the held call. For example, if the held party hangs up, the call state can transition to disconnected.

In a bridged situation, a lineHold operation may possibly not actually place the call on hold, because the status of other stations on the call can govern (for example, attempting to "hold" a call when other stations are participating is not be possible); instead, the call can simply be changed to the LINECONNECTEDMODE_INACTIVE mode if it remains connected at other stations.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_CALLSTATE, linePrepareAddToConference, lineSetupConference, lineSetupTransfer, lineUnhold


lineInitialize

The lineInitialize function is obsolete. It continues to be exported by tapi.dll and tapi32.dll for backward compatibility with applications using API versions 1.3 and 1.4.

Applications using API version 2.0 or later must use lineInitializeEx instead.

For TAPI Versions 1.4 and earlier

The lineInitialize function initializes the application's use of Tapi.dll for subsequent use of the line abstraction. The function registers the application's specified notification mechanism and returns the number of line devices available to the application. A line device is any device that provides an implementation for the line-prefixed functions in TAPI.

LONG lineInitialize(
  LPHLINEAPP lphLineApp,
  HINSTANCE hInstance,
  LINECALLBACK lpfnCallback,
  LPCSTR lpszAppName,
  LPDWORD lpdwNumDevs
);

Parameters

lphLineApp
A pointer to a location that is filled with the application's usage handle for TAPI.
hInstance
The instance handle of the client application or DLL.
lpfnCallback
The address of a callback function that is invoked to determine status and events on the line device, addresses, or calls. For more information, see lineCallbackFunc.
lpszAppName
A pointer to a NULL-terminated ASCII string that contains only displayable ASCII characters. If this parameter is not NULL, it contains an application-supplied name for the application. This name is provided in the LINECALLINFO structure to indicate, in a user-friendly way, which application originated, or originally accepted or answered the call. This information can be useful for call logging purposes. If lpszAppName is NULL, the application's filename is used instead.
lpdwNumDevs
A pointer to a DWORD-sized location. Upon successful completion of this request, this location is filled with the number of line devices available to the application.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NODRIVER, LINEERR_NODEVICE, LINEERR_NOMEM, LINEERR_NOMULTIPLEINSTANCE.

Remarks

If LINEERR_REINIT is returned and TAPI reinitialization has been requested (for example as a result of adding or removing a telephony service provider), then lineInitialize requests are rejected with this error until the last application shuts down its usage of the API (using lineShutdown). At that time, the new configuration becomes effective and applications are once again permitted to call lineInitialize. If the LINEERR_INVALPARAM error value is returned, the specified hInstance parameter is invalid.

The application can refer to individual line devices by using line device identifiers that range from zero to dwNumDevs minus one. An application should not assume that these line devices are capable of anything beyond what is specified by the Basic Telephony subset without first querying their device capabilities using lineGetDevCaps and lineGetAddressCaps.

Applications should not invoke lineInitialize without subsequently opening a line (at least for monitoring). If the application is not monitoring and not using any devices, it should call lineShutdown so that memory resources allocated by tapi.dll can be released if unneeded, and tapi.dll itself can be unloaded from memory while not needed.

Another reason for performing a lineShutdown is that if a user changes the device configuration (adds or removes a line or phone), there is no way for TAPI to notify an application that has a line or phone handle open at the time. After a reconfiguration has taken place, causing a LINEDEVSTATE_REINIT message to be sent, no applications can open a device until all applications have performed a lineShutdown. If any service provider fails to initialize properly, this function fails and returns the error indicated by the service provider.

On all TAPI platforms, lineInitialize is equivalent to lineInitializeEx() using the LINEINITIALIZEEXOPTION_USEHIDDENWINDOW option.

QuickInfo

Version: Use TAPI version 1.4. Not available in TAPI 2.0 or later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

lineCallbackFunc, LINECALLINFO, lineGetAddressCaps, lineGetDevCaps, lineInitializeEx, lineShutdown


lineInitializeEx

The lineInitializeEx function initializes the application's use of TAPI for subsequent use of the line abstraction. It registers the application's specified notification mechanism and returns the number of line devices available to the application. A line device is any device that provides an implementation for the line-prefixed functions in the Telephony API.

LONG lineInitializeEx(
  LPHLINEAPP lphLineApp,
  HINSTANCE hInstance,
  LINECALLBACK lpfnCallback,
  LPCSTR lpszFriendlyAppName,
  LPDWORD lpdwNumDevs,
  LPDWORD lpdwAPIVersion,
  LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams
);

Parameters

lphLineApp
A pointer to a location that is filled with the application's usage handle for TAPI.
hInstance
The instance handle of the client application or DLL. The application or DLL can pass NULL for this parameter, in which case TAPI uses the module handle of the root executable of the process (for purposes of identifying call handoff targets and media mode priorities).
lpfnCallback
The address of a callback function that is invoked to determine status and events on the line device, addresses, or calls, when the application is using the "hidden window" method of event notification (for more information see lineCallbackFunc). This parameter is ignored and should be set to NULL when the application chooses to use the "event handle" or "completion port" event notification mechanisms.
lpszFriendlyAppName
A pointer to a NULL-terminated ASCII string that contains only displayable ASCII characters. If this parameter is not NULL, it contains an application-supplied name for the application. This name is provided in the LINECALLINFO structure to indicate, in a user-friendly way, which application originated, or originally accepted or answered the call. This information can be useful for call-logging purposes. If lpszFriendlyAppName is NULL, the application's module filename is used instead (as returned by the Windows API GetModuleFileName).
lpdwNumDevs
A pointer to a DWORD-sized location. Upon successful completion of this request, this location is filled with the number of line devices available to the application.
lpdwAPIVersion
A pointer to a DWORD-sized location. The application must initialize this DWORD, before calling this function, to the highest API version it is designed to support (for example, the same value it would pass into dwAPIHighVersion parameter of lineNegotiateAPIVersion). Artificially high values must not be used; the value must be accurately set (for this release, to 0x00020000). TAPI translates any newer messages or structures into values or formats supported by the application's version. Upon successful completion of this request, this location is filled with the highest API version supported by TAPI (for this release, 0x00020000), thereby allowing the application to detect and adapt to having been installed on a system with an older version of TAPI.
lpLineInitializeExParams
A pointer to a structure of type LINEINITIALIZEEXPARAMS containing additional parameters used to establish the association between the application and TAPI (specifically, the application's selected event notification mechanism and associated parameters).

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NOMEM, LINEERR_INVALPARAM.

Remarks

Applications must select one of three mechanisms by which TAPI notifies the application of telephony events: Hidden Window, Event Handle, or Completion Port.

The Hidden Window mechanism is selected by specifying LINEINITIALIZEEXOPTION_USEHIDDENWINDOW in the dwOptions member in the LINEINITIALIZEEXPARAMS structure. In this mechanism (which is the only mechanism available to TAPI verson 1.x applications), TAPI creates a window in the context of the application during the lineInitializeEx function, and subclasses the window so that all messages posted to it are handled by a WNDPROC in TAPI itself. When TAPI has a message to deliver to the application, TAPI posts a message to the hidden window. When the message is received (which can happen only when the application calls the Windows GetMessage API), Windows switches the process context to that of the application and invokes the WNDPROC in TAPI. TAPI then delivers the message to the application by calling the LineCallbackProc, a pointer to which the application provided as a parameter in its call to lineInitializeEx (or lineInitialize, for TAPI version 1.3 and 1.4 applications). This mechanism requires the application to have a message queue (which is not desirable for service processes) and to service that queue regularly to avoid delaying processing of telephony events. The hidden window is destroyed by TAPI during the lineShutdown function.

The Event Handle mechanism is selected by specifying LINEINITIALIZEEXOPTION_USEEVENT in the dwOptions member in the LINEINITIALIZEEXPARAMS structure. In this mechanism, TAPI creates an event object on behalf of the application, and returns a handle to the object in the hEvent member in LINEINITIALIZEEXPARAMS. The application must not manipulate this event in any manner (for example, must not call SetEvent, ResetEvent, CloseHandle, and so on) or undefined behavior results; the application can only wait on this event using functions such as WaitForSingleObject or MsgWaitForMultipleObjects. TAPI signals this event whenever a telephony event notification is pending for the application; the application must call lineGetMessage to fetch the contents of the message. The event is reset by TAPI when no events are pending. The event handle is closed and the event object destroyed by TAPI during the lineShutdown function. The application is not required to wait on the event handle that is created; the application could choose instead to call lineGetMessage and have it block waiting for a message to be queued.

The Completion Port mechanism is selected by specifying LINEINITIALIZEEXOPTION_USECOMPLETION PORT in the dwOptions member in the LINEINITIALIZEEXPARAMS structure. In this mechanism, whenever a telephony event needs to be sent to the application, TAPI sends it using PostQueuedCompletionStatus to the completion port that the application specified in the hCompletionPort member in LINEINITIALIZEEXPARAMS, tagged with the completion key that the application specified in the dwCompletionKey member in LINEINITIALIZEEXPARAMS. The application must have previously created the completion port using CreateIoCompletionPort. The application retrieves events using GetQueuedCompletionStatus. Upon return from GetQueuedCompletionStatus, the application has the specified dwCompletionKey written to the DWORD pointed to by the lpCompletionKey parameter, and a pointer to a LINEMESSAGE structure returned to the location pointed to by lpOverlapped. After the application has processed the event, it is the application's responsibility to call LocalFree to release the memory used to contain the LINEMESSAGE structure. Because the application created the completion port (thereby allowing it to be shared for other purposes), the application must close it; the application must not close the completion port until after calling lineShutdown.

When a multithreaded application is using the Event Handle mechanism and more than one thread is waiting on the handle, or the Completion Port notification mechanism and more than one thread is waiting on the port, it is possible for telephony events to be processed out of sequence. This is not due to the sequence of delivery of events from TAPI, but would be caused by the time slicing of threads or the execution of threads on separate processors.

If LINEERR_REINIT is returned and TAPI reinitialization has been requested, for example as a result of adding or removing a telephony service provider, then lineInitializeEx requests are rejected with this error until the last application shuts down its usage of the API (using lineShutdown), at which time the new configuration becomes effective and applications are once again permitted to call lineInitializeEx.

If the LINEERR_INVALPARAM error value is returned, the specified hInstance parameter is invalid.

The application can refer to individual line devices by using line device identifiers that range from zero to dwNumDevs minus one. An application should not assume that these line devices are capable of any particular TAPI function without first querying their device capabilities by lineGetDevCaps and lineGetAddressCaps.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, lineCallbackFunc, LINECALLINFO, lineGetAddressCaps, lineGetDevCaps, lineGetMessage, lineInitialize, LINEINITIALIZEEXPARAMS, LINEMESSAGE, lineNegotiateAPIVersion, lineShutdown


lineMakeCall

The lineMakeCall function places a call on the specified line to the specified destination address. Optionally, call parameters can be specified if anything but default call setup parameters are requested.

LONG lineMakeCall(
  HLINE hLine,
  LPHCALL lphCall,
  LPCSTR lpszDestAddress,
  DWORD dwCountryCode,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

hLine
A handle to the open line device on which a call is to be originated.
lphCall
A pointer to an HCALL handle. The handle is only valid after the LINE_REPLY message is received by the application indicating that the lineMakeCall function successfully completed. Use this handle to identify the call when invoking other telephony operations on the call. The application is initially the sole owner of this call. This handle is void if the function returns an error (synchronously or asynchronously by the reply message).
lpszDestAddress
A pointer to the destination address. This follows the standard dialable number format. This pointer can be NULL for non-dialed addresses (as with a hot phone) or when all dialing is performed using lineDial. In the latter case, lineMakeCall allocates an available call appearance that would typically remain in the dialtone state until dialing begins. Service providers that have inverse multiplexing capabilities can allow an application to specify multiple addresses at once.
dwCountryCode
The country code of the called party. If a value of 0 is specified, a default is used by the implementation.
lpCallParams
A pointer to a LINECALLPARAMS structure. This structure allows the application to specify how it wants the call to be set up. If NULL is specified, a default 3.1 kHz voice call is established and an arbitrary origination address on the line is selected. This structure allows the application to select elements such as the call's bearer mode, data rate, expected media mode, origination address, blocking of caller ID information, and dialing parameters.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_ADDRESSBLOCKED, LINEERR_INVALLINEHANDLE, LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_CALLUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_DIALBILLING, LINEERR_INVALPARAM, LINEERR_DIALDIALTONE, LINEERR_INVALPOINTER, LINEERR_DIALPROMPT, LINEERR_INVALRATE, LINEERR_DIALQUIET, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_RATEUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALBEARERMODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALCALLPARAMS, LINEERR_UNINITIALIZED, LINEERR_INVALCOUNTRYCODE, LINEERR_USERUSERINFOTOOBIG.

Remarks

If LINEERR_INVALLINESTATE is returned, the line is currently not in a state in which this operation can be performed. A list of currently valid operations can be found in the dwLineFeatures member (of the type LINEFEATURE_) in the LINEDEVSTATUS structure. Calling lineGetLineDevStatus updates the information in LINEDEVSTATUS. If LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE, or LINEERR_DIALPROMPT is returned, none of the actions otherwise performed by lineMakeCall have occurred; for example, none of the dialable address prior to the offending character has been dialed, no hookswitch state has changed, and so on.

After dialing has completed, several LINE_CALLSTATE messages are usually sent to the application to notify it about the progress of the call. No generally valid sequence of call-state transitions is specified, as no single fixed sequence of transitions can be guaranteed in practice. A typical sequence can cause a call to transition from dialtone, dialing, proceeding, ringback, to connected. With non-dialed lines, the call can typically transition directly to connected state.

An application has the option to specify an originating address on the specified line device. A service provider that models all stations on a switch as addresses on a single line device allows the application to originate calls from any of these stations using lineMakeCall.

The call parameters allow the application to make non-voice calls or request special call setup options that are not available by default.

An application can partially dial using lineMakeCall and continue dialing using lineDial. To abandon a call attempt, use lineDrop.

After lineMakeCall returns a success reply message to the application, a LINE_CALLSTATE message is sent to the application to indicate the current state of the call. This state is not necessarily LINECALLSTATE_DIALTONE.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINE_CALLSTATE, LINE_REPLY, LINECALLPARAMS, LINEDEVSTATUS, lineDial, lineDrop, lineGetLineDevStatus


lineMonitorDigits

The lineMonitorDigits function enables and disables the unbuffered detection of digits received on the call. Each time a digit of the specified digit mode is detected, a message is sent to the application indicating which digit has been detected.

LONG lineMonitorDigits(
  HCALL hCall,
  DWORD dwDigitModes
);

Parameters

hCall
A handle to the call on which digits are to be detected. The call state of hCall can be any state except idle or disconnected.
dwDigitModes
The digit mode or modes that are to be monitored. If dwDigitModes is zero, digit monitoring is canceled. This parameter can have multiple flags set, and uses the following LINEDIGITMODE_ constants:
LINEDIGITMODE_PULSE
Detect digits as audible clicks that are the result of rotary pulse sequences. Valid digits for pulse are '0' through '9'.
LINEDIGITMODE_DTMF
Detect digits as DTMF tones. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.
LINEDIGITMODE_DTMFEND
Detect and provide application notification of DTMF down edges. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

This function is considered successful if digit monitoring has been correctly initiated, not when digit monitoring has terminated. Digit monitoring remains in effect until it is explicitly disabled by calling lineMonitorDigits with dwDigitModes set to zero, until the call transitions to idle, or when the application deallocates its call handle for the call. Although this function can be invoked in any call state, digits are usually detected only while the call is in the connected state.

Each time a digit is detected, a LINE_MONITORDIGITS message is sent to the application passing the detected digit as a parameter.

An application can use lineMonitorDigits to enable or disable unbuffered digit detection. It can use lineGatherDigits for buffered digit detection. After buffered digit gathering is complete, a LINE_GATHERDIGITS message is sent to the application. Both buffered and unbuffered digit detection can be enabled on the same call simultaneously.

Monitoring of digits on a conference call applies only to the hConfCall, not to the individual participating calls.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_GATHERDIGITS, LINE_MONITORDIGITS, lineGatherDigits


lineMonitorMedia

The lineMonitorMedia function enables and disables the detection of media modes on the specified call. When a media mode is detected, a message is sent to the application.

LONG lineMonitorMedia(
  HCALL hCall,
  DWORD dwMediaModes
);

Parameters

hCall
A handle to the call. The call state of hCall can be any state except idle.
dwMediaModes
The media modes to be monitored. A value of 0 for the dwMediaModes parameter cancels all media mode detection. This parameter can have multiple flags set. This parameter uses the following LINEMEDIAMODE_ constants:
LINEMEDIAMODE_INTERACTIVEVOICE
The application can handle calls of the interactive voice media type (it manages live voice calls).
LINEMEDIAMODE_AUTOMATEDVOICE
Voice energy is present on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM
The application can handle calls with the data modem media mode.
LINEMEDIAMODE_G3FAX
The application can handle calls of the group 3 fax media type.
LINEMEDIAMODE_G4FAX
The application can handle calls of the group 4 fax media type.
LINEMEDIAMODE_TDD
The application can handle calls with the TDD (Telephony Devices for the Deaf) media mode.
LINEMEDIAMODE_DIGITALDATA
The application can handle calls of the digital data media type
LINEMEDIAMODE_TELETEX
The application can handle calls with the teletex media mode.
LINEMEDIAMODE_VIDEOTEX
The application can handle calls with the videotex media mode.
LINEMEDIAMODE_TELEX
The application can handle calls with the telex media mode.
LINEMEDIAMODE_MIXED
The application can handle calls with the ISDN mixed media mode.
LINEMEDIAMODE_ADSI
The application can handle calls with the ADSI (Analog Display Services Interface) media mode.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

The media modes specified with lineOpen relate only to enabling the detection of these media modes by the service provider for the purpose of handing off new incoming calls to the proper application. They do not impact any of the media-mode notification messages that are expected because of a previous invocation of lineMonitorMedia.

This function is considered successful if media mode monitoring has been correctly initiated, not when media mode monitoring has terminated. Media monitoring for a given media mode remains in effect until it is explicitly disabled by calling lineMonitorMedia with a dwMediaModes parameter set to zero, until the call transitions to idle, or when the application deallocates its call handle for the call. The lineMonitorMedia function is primarily an event reporting mechanism. The media mode of the call, as indicated in LINECALLINFO, is not affected by the service provider's detection of the media mode. Only the controlling application can change a call's media mode.

Default media monitoring performed by the service provider corresponds to the union of all media modes specified on lineOpen.

Although this function can be invoked in any call state, a call's media mode can typically only be detected while the call is in certain call states. These states can be device specific. For example, in ISDN, a message can indicate the media mode of the media stream before the media stream exists. Similarly, distinctive ringing or the called identifier information about the call can be used to identify the media mode of a call. Otherwise, the call may have to be answered (call in the connected state) to allow a service provider to determine the call's media mode by filtering the media stream. Because filtering a call's media stream implies a computational overhead, applications should disable media monitoring when not required. By default, media monitoring is enabled for newly incoming calls, because a call's media mode selects the application that should handle the call.

An outgoing application that deals with voice media modes may want to monitor the call for silence (a tone) to distinguish who or what is at the called end of a call. For example, a person at home can answer calls with just a short "hello." A person in the office can provide a longer greeting, indicating name and company name. An answering machine can typically have an even longer greeting.

Because media-mode detection enabled by lineMonitorMedia is implemented as a read-only operation of the call's media stream, it is not disruptive.

Monitoring of media on a conference call applies only to the hConfCall parameter, not to the individual participating calls.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINECALLINFO, lineOpen


lineMonitorTones

The lineMonitorTones function enables and disables the detection of inband tones on the call. Each time a specified tone is detected, a message is sent to the application.

LONG lineMonitorTones(
  HCALL hCall,
  LPLINEMONITORTONE const lpToneList,
  DWORD dwNumEntries
);

Parameters

hCall
A handle to the call on whose voice channel tones are to be monitored. The call state of hCall can be any state except idle.
lpToneList
A list of tones to be monitored, of type LINEMONITORTONE. Each tone in this list has an application-defined tag field that is used to identify individual tones in the list to report a tone detection. Tone monitoring in progress is canceled or changed by calling this operation with either NULL for lpToneList or with another tone list.
dwNumEntries
The number of entries in lpToneList. This parameter is ignored if lpToneList is NULL.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_INVALCALLSTATE, LINEERR_INVALPOINTER, LINEERR_INVALTONE, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

Remarks

This function succeeds if tone monitoring has been correctly initiated, not when tone monitoring has terminated. Tone monitoring remains in effect until it is explicitly disabled by calling lineMonitorTones with another tone list (or NULL), until the call transitions to idle, or when the application deallocates its call handle for the call.

Although this function can be invoked in any call state, tones can typically only be detected while the call is in the connected state. Tone detection typically requires computational resources. Depending on the service provider and other activities that compete for such resources, the number of tones that can be detected can vary over time. Also, an equivalent amount of resources can be consumed for monitoring a single triple frequency tone versus three single frequency tones. If resources are overcommitted, the LINEERR_RESOURCEUNAVAIL error is returned.

The lineMonitorTones function is also used to detect silence. Silence is specified as a tone with a frequency of zero.

Monitoring of tones on a conference call applies only to the hConfCall, not to the individual participating calls

If the LINEERR_INVALPOINTER error value is returned, the specified lpToneList parameter is invalid or the value specified by the dwNumEntries parameter is too large.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINEMONITORTONE


lineNegotiateAPIVersion

The lineNegotiateAPIVersion function allows an application to negotiate an API version to use.

LONG lineNegotiateAPIVersion(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  DWORD dwAPILowVersion,
  DWORD dwAPIHighVersion,
  LPDWORD lpdwAPIVersion,
  LPLINEEXTENSIONID lpExtensionID
);

Parameters

hLineApp
The handle to the application's registration with TAPI.
dwDeviceID
The line device to be queried.
dwAPILowVersion
The least recent API version the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.
dwAPIHighVersion
The most recent API version the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.
lpdwAPIVersion
A pointer to a DWORD-sized location that contains the API version number that was negotiated. If negotiation succeeds, this number is in the range between dwAPILowVersion and dwAPIHighVersion.
lpExtensionID
A pointer to a structure of type LINEEXTENSIONID. If the service provider for the specified dwDeviceID supports provider-specific extensions, then, upon a successful negotiation, this structure is filled with the extension identifier of these extensions. This structure contains all zeros if the line provides no extensions. An application can ignore the returned parameter if it does not use extensions.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_OPERATIONUNAVAIL, LINEERR_NODEVICE.

Remarks

Use lineInitializeEx to determine the number of line devices present in the system. The device identifier specified by dwDeviceID varies from zero to one less than the number of line devices present.

The lineNegotiateAPIVersion function is used to negotiate the API version number to use. It also retrieves the extension identifier supported by the line device, and returns zeros if no extensions are supported. If the application wants to use the extensions defined by the returned extension identifier, it must call lineNegotiateExtVersion to negotiate the extension version to use.

The API version number negotiated is that under which TAPI can operate. If version ranges do not overlap, the application and API or service provider versions are incompatible and an error is returned.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINEEXTENSIONID, lineInitializeEx, lineNegotiateExtVersion, TAPI Versions


lineNegotiateExtVersion

The lineNegotiateExtVersion function allows an application to negotiate an extension version to use with the specified line device. This operation need not be called if the application does not support extensions.

LONG lineNegotiateExtVersion(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  DWORD dwAPIVersion,
  DWORD dwExtLowVersion,
  DWORD dwExtHighVersion,
  LPDWORD lpdwExtVersion
);

Parameters

hLineApp
The handle to the application's registration with TAPI.
dwDeviceID
The line device to be queried.
dwAPIVersion
The API version number that was negotiated for the specified line device using lineNegotiateAPIVersion.
dwExtLowVersion
The least recent extension version of the extension identifier returned by lineNegotiateAPIVersion that the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.
dwExtHighVersion
The most recent extension version of the extension identifier returned by lineNegotiateAPIVersion that the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.
lpdwExtVersion
A pointer to a DWORD-sized location that contains the extension version number that was negotiated. If negotiation succeeds, this number is in the range between dwExtLowVersion and dwExtHighVersion.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NODRIVER, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NODEVICE, LINEERR_OPERATIONUNAVAIL.

Remarks

Use lineInitializeEx to determine the number of line devices present in the system. The device identifier specified by dwDeviceID varies from zero to one less than the number of line devices present.

The lineNegotiateAPIVersion function negotiates the API version number to use. It also retrieves the extension identifier supported by the line device, which is zeros if no extensions are provided. Version numbers should be incremented by one for each release. Leaving gaps in release version numbering can cause unexpected results.

If the application wants to use the extensions defined by the returned extension identifier, it must call lineNegotiateExtVersion to negotiate the extension version to use.

The extension version number negotiated is that under which the application and service provider must both operate. If version ranges do not overlap, the application and service provider versions are incompatible and an error is returned.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Extended Telephony Services Reference, lineInitializeEx, lineNegotiateAPIVersion


lineOpen

The lineOpen function opens the line device specified by its device identifier and returns a line handle for the corresponding opened line device. This line handle is used in subsequent operations on the line device.

LONG lineOpen(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  LPHLINE lphLine,
  DWORD dwAPIVersion,
  DWORD dwExtVersion,
  DWORD dwCallbackInstance,
  DWORD dwPrivileges,
  DWORD dwMediaModes,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

hLineApp
A handle to the application's registration with TAPI.
dwDeviceID
Identifies the line device to be opened. It can either be a valid device identifier or the value:
LINEMAPPER
This value is used to open a line device in the system that supports the properties specified in lpCallParams. The application can use lineGetID to determine the identifier of the line device that was opened.
lphLine
A pointer to an HLINE handle that is then loaded with the handle representing the opened line device. Use this handle to identify the device when invoking other functions on the open line device.
dwAPIVersion
The API version number under which the application and Telephony API have agreed to operate. This number is obtained with lineNegotiateAPIVersion.
dwExtVersion
The extension version number under which the application and the service provider agree to operate. This number is zero if the application does not use any extensions. This number is obtained with lineNegotiateExtVersion.
dwCallbackInstance
User-instance data passed back to the application with each message associated with this line or with addresses or calls on this line. This parameter is not interpreted by the Telephony API.
dwPrivileges
The privilege the application wants for the calls it is notified for. This parameter can be a combination of the LINECALLPRIVILEGE_ constants. For applications using TAPI version 2.0 or later, values for this parameter can also be combined with the LINEOPENOPTION_ constants:
LINECALLPRIVILEGE_NONE
The application can make only outgoing calls.
LINECALLPRIVILEGE_MONITOR
The application can monitor only incoming and outgoing calls.
LINECALLPRIVILEGE_OWNER
The application can own only incoming calls of the types specified in dwMediaModes.
LINECALLPRIVILEGE_MONITOR + LINECALLPRIVILEGE_OWNER
The application can own only incoming calls of the types specified in dwMediaModes, but if it is not an owner of a call, it is a monitor.
LINEOPENOPTION_SINGLEADDRESS
The application is interested only in new calls that appear on the address specified by the dwAddressID member in the LINECALLPARAMS structure pointed to by the lpCallParams parameter (which must be specified). If LINEOPENOPTION_SINGLEADDRESS is specified but either lpCallParams is invalid or the included dwAddressID does not exist on the line, the open fails with LINERR_INVALADDRESSID.

In addition to setting the dwAddressID member of the LINECALLPARAMS structure to the desired address, the application must also set dwAddressMode in LINECALLPARAMS to LINEADDRESSMODE_ADDRESSID.

The LINEOPENOPTION_SINGLEADDRESS option affects only TAPI's assignment of initial call ownership of calls created by the service provider using a LINE_NEWCALL message. An application that opens the line with LINECALLPRIVILEGE_MONITOR continues to receive monitoring handles to all calls created on the line. Furthermore, the application is not restricted in any way from making calls or performing other operations that affect other addresses on the opened line.

LINEOPENOPTION_PROXY
The application is willing to handle certain types of requests from other applications that have the line open, as an adjunct to the service provider. Requests are delivered to the application using LINE_PROXYREQUEST messages; the application responds to them by calling lineProxyResponse, and can also generate TAPI messages to other applications having the line open by calling lineProxyMessage.

When this option is specified, the application must also indicate which specific proxy requests it is prepared to handle. It does so by passing, in the lpCallParams parameter, a pointer to a LINECALLPARAMS structure in which the dwDevSpecificSize and dwDevSpecificOffset members have been set to delimit an array of DWORDs. Each element of this array shall contain one of the LINEPROXYREQUEST_ constants. For example, a proxy handler application that supports all five of the Agent-related functions would pass in an array of five DWORDs (dwDevSpecificSize would be 20 decimal) containing the five defined LINEPROXYREQUEST_ values.

The proxy request handler application can run on any machine that has authorization to control the line device. However, requests are always routed through the server on which the service provider is executing that actually controls the line device. Thus, it is most efficient if the application handling proxy requests (such as ACD agent control) executes directly on the server along with the service provider.

Subsequent attempts, by the same application or other applications, to open the line device and register to handle the same proxy requests as an application that is already registered fail with LINEERR_NOTREGISTERED.

To stop handling requests on the line, the application simply calls lineClose.

Other flag combinations return the LINEERR_INVALPRIVSELECT error.

dwMediaModes
The media mode or modes of interest to the application. This parameter is used to register the application as a potential target for incoming call and call handoff for the specified media mode. This parameter is meaningful only if the bit LINECALLPRIVILEGE_OWNER in dwPrivileges is set (and ignored if it is not). This parameter uses the following LINEMEDIAMODE_ constants:
LINEMEDIAMODE_UNKNOWN
The application can handle calls of unknown media type (unclassified calls).
LINEMEDIAMODE_INTERACTIVEVOICE
The application can handle calls of the interactive voice media type. That is, it manages voice calls with the human user on this end of the call.
LINEMEDIAMODE_AUTOMATEDVOICE
Voice energy is present on the call. The voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM
The application can handle calls with the data-modem media mode.
LINEMEDIAMODE_G3FAX
The application can handle calls of the group 3 fax media type.
LINEMEDIAMODE_TDD
The application can handle calls with the TDD (Telephony Devices for the Deaf) media mode.
LINEMEDIAMODE_G4FAX
The application can handle calls of the group 4 fax media type.
LINEMEDIAMODE_DIGITALDATA
The application can handle calls of the digital-data media type.
LINEMEDIAMODE_TELETEX
The application can handle calls with the teletex media mode.
LINEMEDIAMODE_VIDEOTEX
The application can handle calls with the videotex media mode.
LINEMEDIAMODE_TELEX
The application can handle calls with the telex media mode.
LINEMEDIAMODE_MIXED
The application can handle calls with the ISDN mixed media mode.
LINEMEDIAMODE_ADSI
The application can handle calls with the ADSI (Analog Display Services Interface) media mode.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.
lpCallParams
A pointer to a structure of type LINECALLPARAMS. This pointer is only used if LINEMAPPER is used; otherwise lpCallParams is ignored. It describes the call parameter that the line device should be able to provide.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_ALLOCATED, LINEERR_LINEMAPPERFAILED, LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_INVALPRIVSELECT, LINEERR_REINIT, LINEERR_NODEVICE, LINEERR_OPERATIONUNAVAIL.

Remarks

If LINEERR_ALLOCATED is returned, the line cannot be opened due to a "persistent" condition, such as that of a serial port being exclusively opened by another process. If LINEERR_RESOURCEUNAVAIL is returned, the line cannot be opened due to a dynamic resource overcommitment such as in DSP processor cycles or memory. This overcommitment can be transitory, caused by monitoring of media mode or tones, and changes in these activities by other applications can make it possible to reopen the line within a short time period. If LINEERR_REINIT is returned and TAPI reinitialization has been requested (for example, as a result of adding or removing a telephony service provider), then lineOpen requests are rejected with this error until the last application shuts down its usage of the API (using lineShutdown); at that time the new configuration becomes effective and applications are once again permitted to call lineInitializeEx.

Opening a line always entitles the application to make calls on any address available on the line. The ability of the application to deal with incoming calls or to be the target of call handoffs on the line is determined by the dwMediaModes parameter. The lineOpen function registers the application as having an interest in monitoring calls or receiving ownership of calls that are of the specified media modes. If the application just wants to monitor calls, then it can specify LINECALLPRIVILEGE_MONITOR. If the application just wants to make outgoing calls, it can specify LINECALLPRIVILEGE_NONE. If the application is willing to control unclassified calls (calls of unknown media mode), it can specify LINECALLPRIVILEGE_OWNER and LINEMEDIAMODE_UNKNOWN. Otherwise, the application should specify the media mode it is interested in handling.

The media modes specified with lineOpen add to the default value for the provider's media mode monitoring for initial incoming call type determination. The lineMonitorMedia function modifies the mask that controls LINE_MONITORMEDIA messages. If a line device is opened with owner privilege and an extension media mode is not registered, then the error LINEERR_INVALMEDIAMODE is returned.

An application that has successfully opened a line device can always initiate calls using lineMakeCall, lineUnpark, linePickup, and lineSetupConference (with a NULL hCall), as well as use lineForward (assuming that doing so is allowed by the device capabilities, line state, and so on).

A single application can specify multiple flags simultaneously to handle multiple media modes. Conflicts can arise if multiple applications open the same line device for the same media mode. These conflicts are resolved by a priority scheme in which the user assigns relative priorities to the applications. Only the highest priority application for a given media mode will ever receive ownership (unsolicited) of a call of that media mode. Ownership can be received when an incoming call first arrives or when a call is handed off.

Any application (including any lower priority application) can always acquire ownership with lineGetNewCalls or lineGetConfRelatedCalls. If an application opens a line for monitoring at a time that calls exist on the line, LINE_CALLSTATE messages for those existing calls are not automatically generated to the new monitoring application. The application can query the number of current calls on the line to determine how many calls exist, and, if it wants, it can call lineGetNewCalls to obtain handles to these calls.

An application that handles automated voice should also select the interactive voice open mode and be assigned the lowest priority for interactive voice. The reason for this is that service providers report all voice media modes as interactive voice. If media mode determination is not performed by the application for the UNKNOWN media type, and no interactive voice application has opened the line device, voice calls would be unable to reach the automated voice application, and would be dropped.

The same application, or different instantiations of the same application, can open the same line multiple times with the same or different parameters.

When an application opens a line device it must specify the negotiated API version and, if it wants to use the line's extensions, it should specify the line's device-specific extension version. These version numbers should have been obtained with lineNegotiateAPIVersion and lineNegotiateExtVersion. Version numbering allows the mixing and matching of different application versions with different API versions and service provider versions.

LINEMAPPER allows an application to select a line indirectly—by means of the services it wants from it. When opening a line device using LINEMAPPER, the following is true: All members from beginning of the LINECALLPARAMS data structure through dwAddressMode are relevant. If dwAddressMode is LINEADDRESSMODE_ADDRESSID it means that any address on the line is acceptable, otherwise if dwAddressMode is LINEADDRESSMODE_DIALABLEADDR, indicating that a specific originating address (phone number) is searched for, or if it is a provider-specific extension, then dwOrigAddressSize/Offset and the portion of the variable part they refer to are also relevant. If dwAddressMode is a provider-specific extension, additional information can be contained in the dwDeviceSpecific variably sized member.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINE_CALLSTATE, LINE_MONITORMEDIA, LINE_PROXYREQUEST, LINECALLPARAMS, lineClose, lineForward, lineGetConfRelatedCalls, lineGetNewCalls, lineInitializeEx, lineMakeCall, lineMonitorMedia, lineNegotiateAPIVersion, lineNegotiateExtVersion, linePickup, lineProxyMessage, lineProxyResponse, lineSetupConference, lineShutdown, lineUnpark


linePark

The linePark function parks the specified call according to the specified park mode.

LONG linePark(
  HCALL hCall,
  DWORD dwParkMode,
  LPCSTR lpszDirAddress,
  LPVARSTRING lpNonDirAddress
);

Parameters

hCall
A handle to the call to be parked. The application must be an owner of the call. The call state of hCall must be connected.
dwParkMode
The park mode with which the call is to be parked. This parameter can have only a single flag set, and uses the following LINEPARKMODE_ constants:
LINEPARKMODE_DIRECTED
The application specifies at which address the call is to be parked in lpszDirAddress.
LINEPARKMODE_NONDIRECTED
This operation reports to the application where the call has been parked in lpNonDirAddress.
lpszDirAddress
A pointer to a NULL-terminated string that indicates the address where the call is to be parked when using directed park. The address is in dialable number format. This parameter is ignored for nondirected park.
lpNonDirAddress
A pointer to a structure of type VARSTRING. For nondirected park, the address where the call is parked is returned in this structure. This parameter is ignored for directed park. Within the VARSTRING structure, dwStringFormat must be set to STRINGFORMAT_ASCII (an ASCII string buffer containing a NULL-terminated string), and the terminating NULL must be accounted for in the dwStringSize. Prior to calling linePark, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESS, LINEERR_NOTOWNER, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALPARKMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

With directed park, the application determines the address at which it wants to park the call. With nondirected park, the switch determines the address and provides this to the application. In either case, a parked call can be unparked by specifying this address.

The parked call typically enters the idle state after it has been successfully parked, and the application should then deallocate its handle to the call. If the application performs a lineUnpark on the parked call, a new call handle is created for the unparked call even if the application has not deallocated its old call handle.

Some switches can remind the user after a call has been parked for some long amount of time. The application sees an offering call with a call reason set to reminder.

On a nondirected park, if the dwTotalSize member in the VARSTRING structure does not specify a sufficient amount of memory to receive the park address, the corresponding reply message returns a LINEERR_STRUCTURETOOSMALL error value. In such cases, there is no way to retrieve the complete park address. When a LINEERR_STRUCTURETOOSMALL error value is returned, the dwNeededSize member of the NonDirAddress structure does not contain a valid value. If a LINEERR_STRUCTURETOOSMALL error value is received from a nondirected linePark, then increase the size of the buffer and call linePark again until it returns either success or a different LINEERR_XXX result.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_REPLY, lineUnpark, VARSTRING


linePickup

The linePickup function picks up a call alerting at the specified destination address and returns a call handle for the picked-up call. If invoked with NULL for the lpszDestAddress parameter, a group pickup is performed. If required by the device, lpszGroupID specifies the group identifier to which the alerting station belongs.

LONG linePickup(
  HLINE hLine,
  DWORD dwAddressID,
  LPHCALL lphCall,
  LPCSTR lpszDestAddress,
  LPCSTR lpszGroupID
);

Parameters

hLine
A handle to the open line device on which a call is to be picked up.
dwAddressID
The address on hLine at which the pickup is to be originated.
lphCall
A pointer to a memory location where the handle to the picked up call is returned. The application is the initial sole owner of the call.
lpszDestAddress
A pointer to a NULL-terminated character buffer that contains the address whose call is to be picked up. The address is in standard dialable address format.
lpszGroupID
A pointer to a NULL-terminated character buffer containing the group identifier to which the alerting station belongs. This parameter is required on some switches to pick up calls outside of the current pickup group.

The lpszGroupID parameter can be specified by itself with a NULL pointer for lpszDestAddress. Alternatively, lpszGroupID can be specified in addition to lpszDestAddress, if required by the device.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESS, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALGROUPID, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED.

Remarks

When a call has been picked up successfully, the application is notified by the LINE_CALLSTATE message about call state changes. The LINECALLINFO structure supplies information about the call that was picked up. It lists the reason for the call as pickup. This structure is available using lineGetCallInfo.

If LINEADDRCAPFLAGS_PICKUPCALLWAIT is TRUE, linePickup can be used to pick up a call for which the user has audibly detected the call-waiting signal but for which the provider is unable to perform the detection. This gives the user a mechanism to "answer" a waiting call even though the service provider was unable to detect the call-waiting signal. Both lpszDestAddress and lpszGroupID pointer parameters must be NULL to pick up a call-waiting call. The linePickup function creates a new call handle for the waiting call and passes that handle to the user. The dwAddressID parameter is most often zero (particularly in single-line residential cases).

After linePickup has been used to pick up the second call, lineSwapHold can be used to toggle between them. The lineDrop function can be used to drop one (and toggle to the other), and so forth. If the user wants to drop the current call and pick up the second call, they should call lineDrop when they get the call-waiting beep, wait for the second call to ring, and then call lineAnswer on the new call handle. The LINEADDRFEATURE_PICKUP flag in the dwAddressFeatures member in LINEADDRESSSTATUS indicates when pickup is actually possible.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_CALLSTATE, LINE_REPLY, LINEADDRESSSTATUS, lineAnswer, LINECALLINFO, lineDrop, lineGetCallInfo, lineSwapHold


linePrepareAddToConference

The linePrepareAddToConference function prepares an existing conference call for the addition of another party.

LONG linePrepareAddToConference(
  HCALL hConfCall,
  LPHCALL lphConsultCall,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

hConfCall
A handle to a conference call. The application must be an owner of this call. The call state of hConfCall must be connected.
lphConsultCall
A pointer to an HCALL handle. This location is then loaded with a handle identifying the consultation call to be added. Initially, the application is the sole owner of this call.
lpCallParams
A pointer to call parameters to be used when establishing the consultation call. This parameter can be set to NULL if no special call setup parameters are desired.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_CALLUNAVAIL, LINEERR_INVALRATE, LINEERR_CONFERENCEFULL, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_NOTOWNER, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALBEARERMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLPARAMS, LINEERR_RATEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCONFCALLHANDLE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALLINESTATE, LINEERR_USERUSERINFOTOOBIG, LINEERR_INVALMEDIAMODE, LINEERR_UNINITIALIZED.

Remarks

If LINEERR_INVALLINESTATE is returned, the line is currently not in a state in which this operation can be performed. A list of currently valid operations can be found in the dwLineFeatures member (of the type LINEFEATURE) in the LINEDEVSTATUS structure. (Calling lineGetLineDevStatus updates the information in LINEDEVSTATUS.)

A conference call handle can be obtained with lineSetupConference or with lineCompleteTransfer that is resolved as a three-way conference call. The linePrepareAddToConference function typically places the existing conference call in the onHoldPendingConference state and creates a consultation call that can be added later to the existing conference call with lineAddToConference.

The consultation call can be canceled using lineDrop. It may also be possible for an application to swap between the consultation call and the held conference call with lineSwapHold.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_REPLY, lineAddToConference, lineCompleteTransfer, LINEDEVSTATUS, lineDrop, lineGetLineDevStatus, lineSetupConference, lineSwapHold


lineProxyMessage

The lineProxyMessage function is used by a registered proxy request handler to generate TAPI messages related to its role. For example, an ACD agent handler can use this function to generate LINE_AGENTSTATUS messages that are received by all applications that have the specified line open. TAPI suppresses generation of the message on the hLine specified in the function parameters.

LONG lineProxyMessage(
  HLINE hLine,
  HCALL hCall,
  DWORD dwMsg,
  DWORD dwParam1,
  DWORD dwParam2,
  DWORD dwParam3
);

Parameters

hLine
A handle to the open line device. This is converted by TAPI into the correct hLine for each application that receives the message.
hCall
If the message is related to a specific call (which it is not, in the case of LINE_AGENTSTATUS), specifies the proxy handler's handle to that call; shall be set to NULL for messages not related to a specific call. This is converted by TAPI into the correct hCall for each application that receives the message.
dwMsg
The TAPI message to be generated. This must be a message that is permitted to be generated by proxy handlers.
dwParam1
dwParam2
dwParam3
The parameters associated with the message to be sent.

Return Values

Returns zero if the function succeeds or one of these negative error values:

LINEERR_INVALLINEHANDLE, LINEERR_INVALCALLHANDLE, LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_NOTREGISTERED, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_AGENTSTATUS


lineProxyResponse

The lineProxyResponse function indicates completion of a proxy request by a registered proxy handler, such as an ACD agent handler on a server.

LONG lineProxyResponse(
  HLINE hLine,
  LPLINEPROXYREQUEST lpProxyRequest,
  DWORD dwResult
);

Parameters

hLine
A handle to the open line device.
lpProxyRequest
The pointer to the proxy request buffer that was given to the application by TAPI in a LINE_PROXYREQUEST message. In the case of proxy requests that return data to the client application, the proxy handler shall have filled in the necessary structure in this buffer before calling this function. The dwNeededSize and dwUsedSize members of the structure to be returned must have been set appropriately.
dwResult
The function result that is to be returned to the calling application in a LINE_REPLY message (generated automatically by TAPI). Must be zero or one of the negative error values defined for the function invoked.

Return Values

Returns zero if the function succeeds or one of these negative error values:

LINEERR_INVALLINEHANDLE, LINEERR_INVALPARAM, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_NOTREGISTERED, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions


lineRedirect

The lineRedirect function redirects the specified offering call to the specified destination address.

LONG lineRedirect(
  HCALL hCall,
  LPCSTR lpszDestAddress,
  DWORD dwCountryCode
);

Parameters

hCall
A handle to the call to be redirected. The application must be an owner of the call. The call state of hCall must be offering.
lpszDestAddress
A pointer to the destination address. This follows the standard dialable number format.
dwCountryCode
The country code of the party the call is redirected to. If a value of 0 is specified, a default is used by the implementation.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESS, LINEERR_NOTOWNER, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

Call redirect allows an application to deflect an offering call to another address without first answering the call. Call redirect differs from call forwarding in that call forwarding is performed by the switch without the involvement of the application; redirection can be done on a call-by-call basis by the application, for example, driven by caller ID information. It differs from call transfer in that transferring a call requires the call first be answered.

After a call has been successfully redirected, the call typically transitions to idle.

Besides redirecting an incoming call, an application may have the option to accept the call using lineAccept, reject the call using lineDrop, or answer the call using lineAnswer. The availability of these operations is dependent on device capabilities.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_REPLY, lineAccept, lineAnswer, lineDrop


lineRegisterRequestRecipient

The lineRegisterRequestRecipient function registers the invoking application as a recipient of requests for the specified request mode.

LONG lineRegisterRequestRecipient(
  HLINEAPP hLineApp,
  DWORD dwRegistrationInstance,
  DWORD dwRequestMode,
  DWORD bEnable
);

Parameters

hLineApp
The application's usage handle for the line portion of TAPI.
dwRegistrationInstance
An application-specific DWORD that is passed back as a parameter of the LINE_REQUEST message. This message notifies the application that a request is pending. This parameter is ignored if bEnable is set to zero. This parameter is examined by TAPI only for registration, not for deregistration. The dwRegistrationInstance value used while deregistering need not match the dwRegistrationInstance used while registering for a request mode.
dwRequestMode
The type or types of request for which the application registers. One or both bits can be set. This parameter uses the following LINEREQUESTMODE_ constants:
LINEREQUESTMODE_MAKECALL
A tapiRequestMakeCall request.
bEnable
If TRUE, the application registers the specified request modes; if FALSE, the application deregisters for the specified request modes.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALAPPHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALREQUESTMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

A telephony-enabled application can request that a call be placed on its behalf by invoking tapiRequestMakeCall. Additionally, other applications can request that information be logged with a given call. The tapiRequestMakeCall requests are queued by TAPI, and the highest priority application that has registered to handle the request is sent a LINE_REQUEST message with an indication of the mode of the request that is pending. This application is typically the user's call-control application.

Next, the call-control application that receives this message invokes lineGetRequest, specifying the request mode and a buffer that is large enough to hold the request. The call-control application then interprets and executes the request.

The recipient application is also automatically deregistered for all requests when it does a lineShutdown.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINE_REQUEST, lineGetRequest, lineShutdown, tapiRequestMakeCall


lineReleaseUserUserInfo

The lineReleaseUserUserInfo function informs the service provider that the application has processed the user-user information contained in the LINECALLINFO structure, and that subsequently received user-user information can now be written into that structure. The service provider sends a LINE_CALLINFO message indicating LINECALLINFOSTATE_USERUSERINFO when new information is available.

LONG lineReleaseUserUserInfo(
  HCALL hCall
);

Parameters

hCall
A handle to the call. The application must be an owner of the call. The call state of hCall can be any state.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED, LINEERR_OPERATIONUNAVAIL.

Remarks

The lineReleaseUserUserInfo function allows the application to control the flow of incoming user-user information on an ISDN connection. When a new, complete user-user information message is received, the service provider informs the application using a LINE_CALLINFO message (specifying LINECALLINFOSTATE_USERUSERINFO). Any number of applications can examine the information (using lineGetCallInfo), but the application owning the call controls when the information is released so that subsequent information can be reported. The service provider will not overwrite previous user-user information in LINECALLINFO with newer information until after lineReleaseUserUserInfo has been called. It is the responsibility of the service provider to buffer subsequently received user-user information until the previous information is released by the application owning the call.

Although this is a new function that older applications would not be expected to call, for backward compatibility, they should not be prevented from doing so. The function works the same way for all applications.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_CALLINFO, LINE_REPLY, LINECALLINFO, lineGetCallInfo


lineRemoveFromConference

The lineRemoveFromConference function removes the specified call from the conference call to which it currently belongs. The remaining calls in the conference call are unaffected.

LONG lineRemoveFromConference(
  HCALL hCall
);

Parameters

hCall
A handle to the call to be removed from the conference. The application must be an owner of this call. The call state of hCall must be conferenced.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED.

Remarks

This operation removes a party that currently belongs to a conference call. After the call has been successfully removed, it may be possible to further manipulate it using its handle. The availability of this operation and its result are likely to be limited in many implementations. For example, in many implementations, only the most recently added party can be removed from a conference, and the removed call can be automatically dropped (becomes idle). Consult the line's device capabilities to determine the available effects of removing a call from a conference.

If the removal of a participant from a conference is supported, the participant call, after it is removed from the conference, enters the call-state listed in the dwRemoveFromConfState member in LINEADDRESSCAPS.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_REPLY, LINEADDRESSCAPS


lineRemoveProvider

The lineRemoveProvider function removes an existing telephony service provider from the telephony system.

LONG lineRemoveProvider(
  DWORD dwPermanentProviderID,
  HWND hwndOwner
);

Parameters

dwPermanentProviderID
The permanent provider identifier of the service provider to be removed.
hwndOwner
A handle to a window to which any dialog boxes which need to be displayed as part of the removal process (for example, a confirmation dialog box by the service provider's TSPI_providerRemove function) would be attached. Can be a NULL value to indicate that any window created during the function should have no owner window.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM, LINEERR_OPERATIONFAILED.

Remarks

If the call to TSPI_providerRemove succeeds, and the telephony system is active at the time, TAPI calls TSPI_lineShutdown and/or TSPI_phoneShutdown on the service provider (depending on which device types are active). Any line or phone handles still held by applications on associated devices are forcibly closed with LINE_CLOSE or PHONE_CLOSE messages (it is preferable for service providers to issue these messages as part of TSPI_providerRemove, after verification with the user). The devices previously under the control of that provider are then marked as "unavailable", so that any future attempts by applications to reference them by device identifier result in LINEERR_NODRIVER.

Although this is a new function that older applications would not be expected to call, for backward compatibility they should not be prevented from doing so. The function works the same way for all applications.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_CLOSE, PHONE_CLOSE


lineSecureCall

The lineSecureCall function secures the call from any interruptions or interference that can affect the call's media stream.

LONG lineSecureCall(
  HCALL hCall
);

Parameters

hCall
A handle to the call to be secured. The application must be an owner of the call. The call state of hCall can be any state.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED.

Remarks

A call can be secured to avoid interference. For example, in an analog environment, call-waiting tones can destroy a fax or modem session on the original call. The lineSecureCall function allows an existing call to be secured. The lineMakeCall function provides the option to secure the call from the time of call setup. The securing of a call remains in effect for the duration of the call.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_REPLY, lineMakeCall


lineSendUserUserInfo

The lineSendUserUserInfo function sends user-user information to the remote party on the specified call.

LONG lineSendUserUserInfo(
  HCALL hCall,
  LPCSTR lpsUserUserInfo,
  DWORD dwSize
);

Parameters

hCall
A handle to the call on which to send user-user information. The application must be an owner of the call. The call state of hCall must be connected, offering, accepted, or ringback.
lpsUserUserInfo
A pointer to a string containing user-user information to be sent to the remote party. User-user information is only sent if supported by the underlying network (see LINEDEVCAPS). The protocol discriminator field for the user-user information, if required, should appear as the first byte of the buffer pointed to by lpsUserUserInfo, and must be accounted for in dwSize.
dwSize
The size in bytes of the user-user information in lpsUserUserInfo.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_USERUSERINFOTOOBIG, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED.

Remarks

This function can be used to send user-user information at any time during a connected call. If the size of the specified information to be sent is larger than what can fit into a single network message (as in ISDN), the service provider is responsible for dividing the information into a sequence of chained network messages (using "more data").

User-user information can also be sent as part of call accept, call reject, and call redirect, and when making calls. User-user information can also be received. The received information is available through the call's call-information record. Whenever user-user information arrives after call offering or prior to call disconnect, a LINE_CALLINFO message with a UserUserInfo parameter notifies the application that user-user information in the call-information record has changed. If multiple network messages are chained, the information is assembled by the service provider and a single message is sent to the application.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_CALLINFO, LINE_REPLY, LINEDEVCAPS


lineSetAgentActivity

The lineSetAgentActivity function sets the agent activity code associated with a particular address.

LONG lineSetAgentActivity(
  HLINE hLine,
  DWORD dwAddressID,
  DWORD dwActivityID
);

Parameters

hLine
Handle to the line device.
dwAddressID
Identifier of the address for which the agent activity code is to be changed.
dwActivityID
The new agent activity. The meaning of all values of this parameter are specific to the application and call center server.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, the function returns one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_INVALADDRESSSTATE, LINEERR_INVALAGENTACTIVITY, LINEERR_INVALLINEHANDLE, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions


lineSetAgentGroup

The lineSetAgentGroup function sets the agent groups into which the agent is logged into on a particular address.

LONG lineSetAgentGroup(
  HLINE hLine,
  DWORD dwAddressID,
  LPLINEAGENTGROUPLIST lpAgentGroupList
);

Parameters

hLine
Handle to the line device.
dwAddressID
Identifier of the address for which the agent information is to be changed.
lpAgentList
Pointer to a LINEAGENTGROUPLIST structure identifying the groups into which the current agent is to be logged in on the address. If the pointer is NULL or the number of groups in the indicated structure is zero, then the agent is logged out of any ACD groups into which it is currently logged in.

Note The "Name" fields in the LINEAGENTGROUPENTRY items in the list are ignored for purposes of this function; the control of the logged-in groups is based on the group identifier values only.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, the function returns one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_INVALADDRESSSTATE, LINEERR_INVALAGENTGROUP, LINEERR_INVALAGENTID, LINEERR_INVALAGENTSKILL, LINEERR_INVALAGENTSUPERVISOR, LINEERR_INVALLINEHANDLE, LINEERR_INVALPARAM, LINEERR_INVALPASSWORD, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINEAGENTGROUPENTRY, LINEAGENTGROUPLIST


lineSetAgentState

The lineSetAgentState function sets the agent state associated with a particular address.

LONG lineSetAgentState(
  HLINE hLine,
  DWORD dwAddressID,
  DWORD dwAgentState,
  DWORD dwNextAgentState
);

Parameters

hLine
Handle to the line device.
dwAddressID
Identifier of the address for which the agent information is to be changed.
dwAgentState
The new agent state. Must be one of the LINEAGENTSTATE_ constants, or zero to leave the agent state unchanged and modify only the next state.
dwNextAgentState
The agent state that should be automatically set when the current call on the address becomes idle. For example, if it is known that after-call work must be performed, this field can be set to LINEAGENTSTATE_WORKAFTERCALL so that a new call is not assigned to the agent after the current call. Must be one of the LINEAGENTSTATE_ constants, or zero to use the default next state configured for the agent.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, the function returns one of these negative error values:

LINEERR_INVALADDRESSID, LINEERR_INVALADDRESSSTATE, LINEERR_INVALAGENTSTATE, LINEERR_INVALLINEHANDLE, LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions


lineSetAppPriority

The lineSetAppPriority function allows an application to set its priority in the handoff priority list for a particular media mode or Assisted Telephony request mode, or to remove itself from the priority list.

LONG lineSetAppPriority(
  LPCSTR lpszAppFilename,
  DWORD dwMediaMode,
  LPLINEEXTENSIONID const lpExtensionID,
  DWORD dwRequestMode,
  LPCSTR lpszExtensionName,
  DWORD dwPriority
);

Parameters

lpszAppFilename
A pointer to a string containing the application executable module filename (without directory information). In TAPI version 2.0 or later, the parameter can specify a filename in either long or 8.3 filename format.
dwMediaMode
The media mode for which the priority of the application is to be set. The value can be one of the LINEMEDIAMODE_ constants; only a single bit may be on. The value zero should be used to set the application priority for Assisted Telephony requests.
lpExtensionID
A pointer to a structure of type LINEEXTENSIONID. This parameter is ignored.
dwRequestMode
If the dwMediaMode parameter is zero, this parameter specifies the Assisted Telephony request mode for which priority is to be set. It must be either LINEREQUESTMODE_MAKECALL or LINEREQUESTMODE_MEDIACALL. This parameter is ignored if dwMediaMode is nonzero.
lpszExtensionName
This parameter is ignored.
dwPriority
The new priority for the application. If the value 0 is passed, the application is removed from the priority list for the specified media or request mode (if it was already not present, no error is generated). If the value 1 is passed, the application is inserted as the highest-priority application for the media or request mode (and removed from a lower-priority position, if it was already in the list). Any other value generates an error.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_INVALREQUESTMODE, LINEERR_INVALAPPNAME, LINEERR_NOMEM, LINEERR_INVALMEDIAMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER.

Remarks

If LINEERR_INVALMEDIAMODE is returned, the value specified in dwMediaMode is not zero and not a LINEMEDIAMODE_ constant, or more than one bit is on in the parameter value.

This function updates the stored priority list. If the telephony system is initialized, it also sets the current, active priorities for applications then running; the new priority is used on the next incoming call or lineHandoff based on media mode.

Although this is a new function which older applications would not be expected to call, for backward compatibility they should not be prevented from doing so. The function works the same way for all applications.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINEEXTENSIONID, lineHandoff


lineSetAppSpecific

The lineSetAppSpecific function enables an application to set the application-specific field of the specified call's call-information record.

LONG lineSetAppSpecific(
  HCALL hCall,
  DWORD dwAppSpecific
);

Parameters

hCall
A handle to the call whose application-specific field needs to be set. The application must be an owner of the call. The call state of hCall can be any state.
dwAppSpecific
The new content of the dwAppSpecific member for the call's LINECALLINFO structure. This value is not interpreted by the Telephony API.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NOTOWNER, LINEERR_OPERATIONUNAVAIL, LINEERR_OPERATIONFAILED.

Remarks

The application-specific field in the LINECALLINFO data structure that exists for each call is not interpreted by the Telephony API or any of its service providers. Its usage is entirely defined by the applications. The field can be read from the LINECALLINFO record returned by lineGetCallInfo. However, lineSetAppSpecific must be used to set the field so that changes become visible to other applications. When this field is changed, all other applications with call handles are sent a LINE_CALLINFO message with an indication that the dwAppSpecific member has changed.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINE_CALLINFO, LINECALLINFO, lineGetCallInfo


lineSetCallData

The lineSetCallData function sets the CallData member in LINECALLINFO. Depending on the service provider implementation, the CallData member can be propagated to all applications having handles to the call, including those on other machines (through the server), and can travel with the call when it is transferred.

LONG lineSetCallData(
  HCALL hCall,
  LPVOID lpCallData,
  DWORD dwSize
);

Parameters

hCall
Handle to the call. The application must have OWNER privilege.
lpCallData
Address of the data to be copied to the CallData member in LINECALLINFO, replacing any existing data.
dwSize
Number of bytes of data to be copied. A value of 0 causes any existing data to be removed.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, the function returns one of these negative error values:

LINEERR_INVALCALLHANDLE, LINEERR_INVALCALLSTATE, LINEERR_INVALPARAM, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_NOTOWNER, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINECALLINFO


lineSetCallParams

The lineSetCallParams function allows an application to change bearer mode and/or the rate parameters of an existing call.

LONG lineSetCallParams(
  HCALL hCall,
  DWORD dwBearerMode,
  DWORD dwMinRate,
  DWORD dwMaxRate,
  LPLINEDIALPARAMS const lpDialParams
);

Parameters

hCall
A handle to the call whose parameters are to be changed. The application must be an owner of the call. The call state of hCall can be any state except idle or disconnected.
dwBearerMode
The new bearer mode for the call. This parameter can have only a single bit set, and it uses the following LINEBEARERMODE_ constants:
LINEBEARERMODE_VOICE
A regular 3.1 kHz analog voice-grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.
LINEBEARERMODE_SPEECH
Corresponds to G.711 speech transmission on the call. The network can use processing techniques such as analog transmission, echo cancellation, and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.
LINEBEARERMODE_MULTIUSE
The multiuse mode defined by ISDN.
LINEBEARERMODE_DATA
The unrestricted data transfer on the call. The data rate is specified separately.
LINEBEARERMODE_ALTSPEECHDATA
The alternate transfer of speech or unrestricted data on the same call (ISDN).
LINEBEARERMODE_NONCALLSIGNALING
Corresponds to a non-call-associated signaling connection from the application to the service provider or switch (treated as a media stream by the Telephony API).
LINEBEARERMODE_PASSTHROUGH
When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 comm functions, for the purpose of configuring or using special features not otherwise supported by the service provider.
dwMinRate
A lower bound for the call's new data rate. The application can accept a new rate as low as this one.
dwMaxRate
An upper bound for the call's new data rate. This is the maximum data rate the application can accept. If an exact data rate is required, dwMinRate and dwMaxRate should be equal.
lpDialParams
A pointer to the new dial parameters for the call, of type LINEDIALPARAMS. This parameter can be left NULL if the call's current dialing parameters are to be used.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_BEARERMODEUNAVAIL, LINEERR_NOTOWNER, LINEERR_INVALBEARERMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RATEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALRATE, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

This operation is used to change the parameters of an existing call. Examples of its usage include changing the bearer mode and/or the data rate of an existing call.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_REPLY, LINEDIALPARAMS


lineSetCallPrivilege

The lineSetCallPrivilege function sets the application's privilege to the specified privilege.

LONG lineSetCallPrivilege(
  HCALL hCall,
  DWORD dwCallPrivilege
);

Parameters

hCall
A handle to the call whose privilege is to be set. The call state of hCall can be any state.
dwCallPrivilege
The privilege the application can have for the specified call. Only a single flag can be set. This parameter uses the following LINECALLPRIVILEGE_ constants:
LINECALLPRIVILEGE_MONITOR
The application requests monitor privilege to the call. These privileges allow the application to monitor state changes and to query information and status about the call.
LINECALLPRIVILEGE_OWNER
The application requests owner privilege to the call. These privileges allow the application to manipulate the call in ways that affect the state of the call.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLPRIVILEGE, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

If the application is the sole owner of a non-idle call and can change its privilege to monitor, a LINEERR_INVALCALLSTATE error is returned. The application can also first drop the call using lineDrop to make the call transition to the idle state and then change its privilege.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, lineDrop


lineSetCallQualityOfService

The lineSetCallQualityOfService function allows the application to attempt to change the quality of service parameters (reserved capacity and performance guarantees) for an existing call. Except for basic parameter validation, this is a straight pass-through to a service provider.

LONG lineSetCallQualityOfService(
  HCALL hCall,
  LPVOID lpSendingFlowspec,
  DWORD dwSendingFlowspecSize,
  LPVOID lpReceivingFlowspec,
  DWORD dwReceivingFlowspecSize
);

Parameters

hCall
Handle to the call. The application must have OWNER privilege.
lpSendingFlowspec
Pointer to memory containing a WinSock2 FLOWSPEC structure followed by provider-specific data. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory in the application process, because TAPI will not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the service provider.
dwSendingFlowspecSize
The total size in bytes of the FLOWSPEC structure and accompanying provider-specific data, equivalent to what would have been stored in SendingFlowspec.len in a WinSock2 QOS structure.
lpReceivingFlowspec
Pointer to memory containing a WinSock2 FLOWSPEC structure followed by provider-specific data. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory in the application process, because TAPI will not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the service provider.
dwReceivingFlowspecSize
The total size in bytes of the FLOWSPEC and accompanying provider-specific data, equivalent to what would have been stored in ReceivingFlowspec.len in a WinSock2 QOS structure.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, the function returns one of these negative error values:

LINEERR_INVALCALLHANDLE, LINEERR_INVALCALLSTATE, LINEERR_INVALPARAM, LINEERR_INVALPOINTER, LINEERR_INVALRATE, LINEERR_NOMEM, LINEERR_NOTOWNER, LINEERR_OPERATIONUNAVAIL, LINEERR_OPERATIONFAILED, LINEERR_RATEUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions


lineSetCallTreatment

The lineSetCallTreatment function sets the sounds a party on a call that is unanswered or on hold hears. Except for basic parameter validation, it is a straight pass-through by TAPI to the service provider.

LONG lineSetCallTreatment(
  HCALL hCall,
  DWORD dwCallTreatment
);

Parameters

hCall
Handle to the call. The application must have OWNER privilege.
dwCallTreatment
One of the call treatments supported on the address on which the call appears, as indicated by LINEADDRESSCAPS. LINEERR_INVALPARAM is returned if the specified treatment is not supported.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, the function returns one of these negative error values:

LINEERR_INVALCALLHANDLE, LINEERR_INVALCALLSTATE, LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_NOTOWNER, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

Remarks

The use of call treatment functionality should be limited to controlling of legacy equipment. New equipment is generally designed so that instead of call treatments being generated by external switching equipment, calls would be connected to PC-based audio sources and signals generated using standard Win32 functions such as the multimedia Wave API.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINEADDRESSCAPS


lineSetCurrentLocation

The lineSetCurrentLocation function sets the location used as the context for address translation.

LONG lineSetCurrentLocation(
  HLINEAPP hLineApp,
  DWORD dwLocation
);

Parameters

hLineApp
The application handle returned by lineInitializeEx. If an application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL.
dwLocation
Specifies a new value for the CurrentLocation entry in the [Locations] section in the registry. It must contain a valid permanent identifier of a Location entry in the [Locations] section, as obtained from lineGetTranslateCaps. If it is valid, the CurrentLocation entry is updated.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALAPPHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALLOCATION, LINEERR_RESOURCEUNAVAIL, LINEERR_NODRIVER, LINEERR_UNINITIALIZED.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, lineGetTranslateCaps, lineInitializeEx


lineSetDevConfig

The lineSetDevConfig function allows the application to restore the configuration of a media stream device on a line device to a setup previously obtained using lineGetDevConfig. For example, the contents of this structure could specify data rate, character format, modulation schemes, and error control protocol settings for a "datamodem" media device associated with the line.

LONG lineSetDevConfig(
  DWORD dwDeviceID,
  LPVOID const lpDeviceConfig,
  DWORD dwSize,
  LPCSTR lpszDeviceClass
);

Parameters

dwDeviceID
The line device to be configured.
lpDeviceConfig
A pointer to the opaque configuration data structure that was returned by lineGetDevConfig in the variable portion of the VARSTRING structure.
dwSize
The number of bytes in the structure pointed to by lpDeviceConfig. This value is returned in the dwStringSize member in the VARSTRING structure returned by lineGetDevConfig.
lpszDeviceClass
A pointer to a NULL-terminated ASCII string that specifies the device class of the device whose configuration is to be set. Valid device class strings are the same as those specified for the lineGetID function.

Return Values

Returns zero if the function succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_NODEVICE.

Remarks

Call states are device specific.

Typically, an application calls lineGetID to identify the media stream device associated with a line, and then calls lineConfigDialog to allow the user to set up the device configuration. It could then call lineGetDevConfig and save the configuration information in a phone book or other database associated with a particular call destination. When the user wants to call the same destination again, this lineSetDevConfig function can be used to restore the configuration settings selected by the user. The lineSetDevConfig, lineConfigDialog, and lineGetDevConfig functions can be used, in that order, to allow the user to view and update the settings.

The exact format of the data contained within the structure is specific to the line and media stream API (device class), is undocumented, and is undefined. The application must treat it as "opaque" and not manipulate the contents directly. Generally, the structure can be sent using this function only to the same device from which it was obtained. Certain telephony service providers may, however, permit structures to be interchanged between identical devices (that is, multiple ports on the same multiport modem card). Such interchangeability is not guaranteed in any way, even for devices of the same device class.

Some service providers may permit the configuration to be set while a call is active, and others may not.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, lineConfigDialog, lineGetDevConfig, lineGetID, VARSTRING


lineSetLineDevStatus

The lineSetLineDevStatus function sets the line device status. Except for basic parameter validation, it is a straight pass-through to the service provider. The service provider sends a LINE_LINEDEVSTATUS message to inform applications of the new state, when set; TAPI does not synthesize these messages.

LONG WINAPI lineSetLineDevStatus(
  DWORD hLine,
  DWORD dwStatusToChange,
  DWORD fStatus
);

Parameters

hLine
Handle to the line device.
dwStatusToChange
One or more of the LINEDEVSTATUSFLAGS_ values.
fStatus
TRUE (–1) to turn on the indicated status bit(s), FALSE (0) to turn off.

Return Values

Returns a positive request identifier if the asynchronous operation starts; otherwise, the function returns one of these negative error values:

LINEERR_INVALLINEHANDLE, LINEERR_INVALLINESTATE, LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONUNAVAIL, LINEERR_OPERATIONFAILED, LINEERR_RESOURCEUNAVAIL, LINEERR_UNINITIALIZED.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.


lineSetMediaControl

The lineSetMediaControl function enables and disables control actions on the media stream associated with the specified line, address, or call. Media control actions can be triggered by the detection of specified digits, media modes, custom tones, and call states.

LONG lineSetMediaControl(
  HLINE hLine,
  DWORD dwAddressID,
  HCALL hCall,
  DWORD dwSelect,
  LPLINEMEDIACONTROLDIGIT const lpDigitList,
  DWORD dwDigitNumEntries,
  LPLINEMEDIACONTROLMEDIA const lpMediaList,
  DWORD dwMediaNumEntries,
  LPLINEMEDIACONTROLTONE const lpToneList,
  DWORD dwToneNumEntries,
  LPLINEMEDIACONTROLCALLSTATE const lpCallStateList,
  DWORD dwCallStateNumEntries
);

Parameters

hLine
A handle to an open line device.
dwAddressID
An address on the given open line device.
hCall
A handle to a call. The application must be an owner of the call. The call state of hCall can be any state.
dwSelect
Specifies whether the media control requested is associated with a single call, is the default for all calls on an address, or is the default for all calls on a line. This parameter can only have a single flag set, and it uses the following LINECALLSELECT_ constants:
LINECALLSELECT_LINE
Selects the specified line device. The hLine parameter must be a valid line handle; hCall and dwAddressID are ignored.
LINECALLSELECT_ADDRESS
Selects the specified address on the line. Both hLine and dwAddressID must be valid; hCall is ignored.
LINECALLSELECT_CALL
Selects the specified call. hCall must be valid; hLine and dwAddressID are both ignored.
lpDigitList
A pointer to the array that contains the digits that are to trigger media control actions, of type LINEMEDIACONTROLDIGIT. Each time a digit in the digit list is detected, the specified media control action is carried out on the call's media stream.

Valid digits for pulse mode are '0' through '9'. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.

dwDigitNumEntries
The number of entries in the lpDigitList.
lpMediaList
A pointer to an array with entries of type LINEMEDIACONTROLMEDIA. The array has dwMediaNumEntries entries. Each entry contains a media mode to be monitored, media-type specific information (such as duration), and a media control field. If a media mode in the list is detected, the corresponding media control action is performed on the call's media stream.
dwMediaNumEntries
The number of entries in lpMediaList.
lpToneList
A pointer to an array with entries of type LINEMEDIACONTROLTONE. The array has dwToneNumEntries entries. Each entry contains a description of a tone to be monitored, duration of the tone, and a media-control field. If a tone in the list is detected, the corresponding media control action is performed on the call's media stream.
dwToneNumEntries
The number of entries in lpToneList.
lpCallStateList
A pointer to an array with entries of type LINEMEDIACONTROLCALLSTATE. The array has dwCallStateNumEntries entries. Each entry contains a call state and a media control action. Whenever the given call transitions into one of the call states in the list, the corresponding media control action is invoked.
dwCallStateNumEntries
The number of entries in lpCallStateList.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_NOMEM, LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSELECT, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATELIST, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITLIST, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_UNINITIALIZED, LINEERR_INVALMEDIALIST, LINEERR_INVALPOINTER, LINEERR_INVALTONELIST.

Remarks

The lineSetMediaControl function is considered successful if media control has been correctly initiated, not when any media control has taken effect. Media control in progress is changed or is canceled by calling this function again with either different parameters or NULLs. If one or more of the parameters lpDigitList, lpMediaList, lpToneList, and lpCallStateList are NULL, then the corresponding digit, media mode, tone, or call state-triggered media control is disabled. To modify just a portion of the media control parameters while leaving the remaining settings in effect, the application should invoke lineSetMediaControl, supplying the previous parameters for those portions that must remain in effect and new parameters for those parts that are to be modified.

If hCall is selected and the call terminates or the application deallocates its handle, media control on that call is canceled.

All applications that are owners of the call are in principle allowed to make media control requests on the call. Only a single media control request can be outstanding on a call across all applications that own the call. Each time lineSetMediaControl is called, the new request overrides any media control then in effect on the call, whether set by the calling application or any other owning application.

Depending on the service provider and other activities that compete for such resources, the number of simultaneous detections that can be made can vary over time. If service provider resources are overcommitted, the LINEERR_RESOURCEUNAVAIL error is returned.

Whether or not media control is supported by the service provider is a device capability.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINEMEDIACONTROLCALLSTATE, LINEMEDIACONTROLDIGIT, LINEMEDIACONTROLMEDIA, LINEMEDIACONTROLTONE


lineSetMediaMode

The lineSetMediaMode function sets the media mode(s) of the specified call in its LINECALLINFO structure.

LONG lineSetMediaMode(
  HCALL hCall,
  DWORD dwMediaModes
);

Parameters

hCall
A handle to the call whose media mode is to be changed. The application must be an owner of the call. The call state of hCall can be any state.
dwMediaModes
The new media mode(s) for the call. As long as the UNKNOWN media mode flag is set, other media mode flags may be set as well. This is used to identify a call's media mode as not fully determined, but narrowed down to one of a small set of specified media modes. If the UNKNOWN flag is not set, only a single media mode can be specified. This parameter uses the following LINEMEDIAMODE_ constants:
LINEMEDIAMODE_UNKNOWN
The target application is the one that handles calls of unknown media mode (unclassified calls).
LINEMEDIAMODE_INTERACTIVEVOICE
The target application is the one that handles calls with the interactive voice media mode (live conversations).
LINEMEDIAMODE_AUTOMATEDVOICE
Voice energy is present on the call, and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM
The target application is the one that handles calls with the data modem media mode.
LINEMEDIAMODE_G3FAX
The target application is the one that handles calls with the group 3 fax media mode.
LINEMEDIAMODE_TDD
The target application is the one that handles calls with the TDD (Telephony Devices for the Deaf) media mode.
LINEMEDIAMODE_G4FAX
The target application is the one that handles calls with the group 4 fax media mode.
LINEMEDIAMODE_DIGITALDATA
The target application is the one that handles calls that are digital data calls.
LINEMEDIAMODE_TELETEX
The target application is the one that handles calls with the teletex media mode.
LINEMEDIAMODE_VIDEOTEX
The target application is the one that handles calls with the videotex media mode.
LINEMEDIAMODE_TELEX
The target application is the one that handles calls with the telex media mode.
LINEMEDIAMODE_MIXED
The target application is the one that handles calls with the ISDN mixed media mode.
LINEMEDIAMODE_ADSI
The target application is the one that handles calls with the ADSI (Analog Display Services Interface) media mode.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_OPERATIONUNAVAIL.

Remarks

The lineSetMediaMode function changes the call's media mode in its LINECALLINFO structure. Typical usage of this operation is either to set a call's media mode to a specific known media mode or to exclude possible media modes as long as the call's media mode is officially unknown (the UNKNOWN media mode flag is set).

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINECALLINFO


lineSetNumRings

The lineSetNumRings function sets the number of rings that must occur before an incoming call is answered. This function can be used to implement a toll-saver-style function. It allows multiple independent applications to each register the number of rings. The function lineGetNumRings returns the minimum number of rings requested. It can be used by the application that answers incoming calls to determine the number of rings it should wait before answering the call.

LONG lineSetNumRings(
  HLINE hLine,
  DWORD dwAddressID,
  DWORD dwNumRings
);

Parameters

hLine
A handle to the open line device.
dwAddressID
An address on the line device.
dwNumRings
The number of rings before a call should be answered in order to honor the toll-saver requests from all applications.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESSID, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

The lineGetNumRings and lineSetNumRings functions, when used in combination, provide a mechanism to support the implementation of toll-saver features across multiple independent applications. If no application ever calls lineSetNumRings, lineGetNumRings returns 0xFFFFFFFF.

An application that is the owner of a call in the offering state and that received a LINE_LINEDEVSTATE ringing message should wait a number of rings equal to the number returned by lineGetNumRings before answering the call in order to honor the toll-saver settings across all applications. A separate LINE_LINEDEVSTATE ringing message is sent to the application for each ring cycle, so the application should count these messages. If this call disconnects before being answered, and another call comes in shortly thereafter, the LINE_CALLSTATE message should allow the application to determine that ringing is related to the second call.

If call classification is performed by TAPI by means of answering incoming calls of unknown media mode and filtering the media stream, TAPI honors this number as well.

Note This operation is purely informational and does not affect the state of any calls on the line device.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINE_CALLSTATE, LINE_LINEDEVSTATE, lineGetNumRings


lineSetStatusMessages

The lineSetStatusMessages function enables an application to specify which notification messages to receive for events related to status changes for the specified line or any of its addresses.

LONG lineSetStatusMessages(
  HLINE hLine,
  DWORD dwLineStates,
  DWORD dwAddressStates
);

Parameters

hLine
A handle to the line device.
dwLineStates
A bit array that identifies for which line-device status changes a message is to be sent to the application. This parameter uses the following LINEDEVSTATE_ constants:
LINEDEVSTATE_OTHER
Device-status items other than those listed below have changed. The application should check the current device status to determine which items have changed.
LINEDEVSTATE_RINGING
The switch tells the line to alert the user. Service providers notify applications on each ring cycle by sending LINE_LINEDEVSTATE messages containing this constant. For example, in the United States, service providers send a message with this constant every six seconds.
LINEDEVSTATE_CONNECTED
The line was previously disconnected and is now connected to TAPI.
LINEDEVSTATE_DISCONNECTED
This line was previously connected and is now disconnected from TAPI.
LINEDEVSTATE_MSGWAITON
The "message waiting" indicator is turned on.
LINEDEVSTATE_MSGWAITOFF
The "message waiting" indicator is turned off.
LINEDEVSTATE_INSERVICE
The line is connected to TAPI. This happens when TAPI is first activated, or when the line wire is physically plugged in and in service at the switch while TAPI is active.
LINEDEVSTATE_OUTOFSERVICE
The line is out of service at the switch or physically disconnected. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_MAINTENANCE
Maintenance is being performed on the line at the switch. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_OPEN
The line has been opened by some application.
LINEDEVSTATE_CLOSE
The line has been closed by some application.
LINEDEVSTATE_NUMCALLS
The number of calls on the line device has changed.
LINEDEVSTATE_NUMCOMPLETIONS
The number of outstanding call completions on the line device has changed.
LINEDEVSTATE_TERMINALS
The terminal settings have changed.
LINEDEVSTATE_ROAMMODE
The roam mode of the line device has changed.
LINEDEVSTATE_BATTERY
The battery level has changed significantly (cellular).
LINEDEVSTATE_SIGNAL
The signal level has changed significantly (cellular).
LINEDEVSTATE_DEVSPECIFIC
The line's device-specific information has changed.
LINEDEVSTATE_REINIT
Items have changed in the configuration of line devices. To become aware of these changes (as with the appearance of new line devices) the application should reinitialize its use of TAPI. New lineInitialize, lineInitializeEx and lineOpen requests are denied until applications have shut down their usage of TAPI. The hDevice parameter of the LINE_LINEDEVSTATE message is left NULL for this state change as it applies to any of the lines in the system. Because of the critical nature of LINEDEVSTATE_REINIT, such messages cannot be masked, so the setting of this bit is ignored and the messages are always delivered to the application.
LINEDEVSTATE_LOCK
The locked status of the line device has changed.
LINEDEVSTATE_REMOVED
Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). Normally, a LINE_LINEDEVSTATE message with this value is immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous TAPI version do not receive any notification.
dwAddressStates
A bit array that identifies for which address status changes a message is to be sent to the application. This parameter uses the following LINEADDRESSSTATE_ constants:
LINEADDRESSSTATE_OTHER
Address-status items other than those listed below have changed. The application should check the current address status to determine which items have changed.
LINEADDRESSSTATE_DEVSPECIFIC
The device-specific item of the address status has changed.
LINEADDRESSSTATE_INUSEZERO
The address has changed to idle (it is now in use by zero stations).
LINEADDRESSSTATE_INUSEONE
The address has changed from idle or from being in use by many bridged stations to being in use by just one station.
LINEADDRESSSTATE_INUSEMANY
The monitored or bridged address has changed from being in use by one station to being used by more than one station.
LINEADDRESSSTATE_NUMCALLS
The number of calls on the address has changed. This is the result of events such as a new incoming call, an outgoing call on the address, or a call changing its hold status.
LINEADDRESSSTATE_FORWARD
The forwarding status of the address has changed (including the number of rings for determining a no-answer condition). The application should check the address status to determine details about the address's current forwarding status.
LINEADDRESSSTATE_TERMINALS
The terminal settings for the address have changed.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESSSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_OPERATIONUNAVAIL.

Remarks

TAPI defines a number of messages that notify applications about events occurring on lines and addresses. An application may not be interested in receiving all address and line status change messages. The lineSetStatusMessages function can be used to select which messages the application receives. By default, address and line status reporting is disabled.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, LINE_CLOSE, LINE_LINEDEVSTATE, lineInitialize, lineInitializeEx, lineOpen


lineSetTerminal

The lineSetTerminal function enables an application to specify which terminal information related to the specified line, address, or call is to be routed. The lineSetTerminal function can be used while calls are in progress on the line to allow an application to route these events to different devices as required.

LONG lineSetTerminal(
  HLINE hLine,
  DWORD dwAddressID,
  HCALL hCall,
  DWORD dwSelect,
  DWORD dwTerminalModes,
  DWORD dwTerminalID,
  DWORD bEnable
);

Parameters

hLine
A handle to an open line device.
dwAddressID
An address on the given open line device.
hCall
A handle to a call. The call state of hCall can be any state, if dwSelect is CALL.
dwSelect
Specifies whether the terminal setting is requested for the line, the address, or just the specified call. If line or address is specified, events either apply to the line or address itself or serve as a default initial setting for all new calls on the line or address. This parameter uses the following LINECALLSELECT_ constants:
LINECALLSELECT_LINE
Selects the specified line device. The hLine parameter must be a valid line handle; hCall and dwAddressID are ignored.
LINECALLSELECT_ADDRESS
Selects the specified address on the line. Both hLine and dwAddressID must be valid; hCall is ignored.
LINECALLSELECT_CALL
Selects the specified call. The hCall parameter must be valid; hLine and dwAddressID are both ignored.
dwTerminalModes
The class or classes of low-level events to be routed to the given terminal. This parameter uses the following LINETERMMODE_ constants:
LINETERMMODE_BUTTONS
The button presses from the terminal to the line.
LINETERMMODE_DISPLAY
The display events from the line to the terminal.
LINETERMMODE_LAMPS
The lamp lighting events from the line to the terminal.
LINETERMMODE_RINGER
The ring requests from the line to the terminal.
LINETERMMODE_HOOKSWITCH
The hookswitch events between the terminal and the line.
LINETERMMODE_MEDIATOLINE
This is the unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIAFROMLINE
This is the unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIABIDIRECT
This is the bidirectional media stream associated with a call on the line and the terminal. Use this value when the routing of both unidirectional channels of a call's media stream cannot be controlled independently. MEDIABIDIRECT is mutually exclusive with MEDIATOLINE and MEDIAFROMLINE.
dwTerminalID
The device identifier of the terminal device where the given events are to be routed. Terminal identifiers are small integers in the range of zero to one less than dwNumTerminals, where dwNumTerminals, and the terminal modes each terminal is capable of handling, are returned by lineGetDevCaps.

Note These terminal identifiers have no relation to other device identifiers and are defined by the service provider using device capabilities.

bEnable
If TRUE, dwTerminalID is valid and the specified event classes are routed to or from that terminal. If FALSE, these events are not routed to or from the terminal device with identifier equal to dwTerminalID.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_NOMEM, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSELECT, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALTERMINALID, LINEERR_UNINITIALIZED, LINEERR_INVALTERMINALMODE.

Remarks

An application can use this function to route certain classes of low-level line events to the specified terminal device or to suppress the routing of these events. For example, voice can be routed to an audio I/O device (headset), lamps and display events can be routed to the local phone device, and button events and ringer events can be suppressed altogether.

This function can be called at any time, even when a call is active on the given line device. This allows a user to switch from using the local phone set to another audio I/O device. This function can be called multiple times to route the same events to multiple terminals simultaneously. To reroute events to a different terminal, the application should first disable routing to the existing terminal and then route the events to the new terminal.

Terminal identifier assignments are made by the line's service provider. Device capabilities indicate only which terminal identifiers the service provider has available. Service providers that do not support this type of event routing would indicate that they have no terminal devices (dwNumTerminals in LINEDEVCAPS would be zero).

Invoking lineSetTerminal on a line or address affects all existing calls on that line or address, but does not affect calls on other addresses. It also sets the default for future calls on that line or address. A line or address that has multiple connected calls active at one time can have different routing in effect for each call.

Disabling the routing of low-level events to a terminal when these events are not currently routed to or from that terminal does not necessarily generate an error so long as the function succeeds (the specified events are not routed to or from that terminal).

TAPI routes call progress tones and messages to the same location as set by the lineSetTerminal function for "media". For example, if audio signals are going to the phone, then so will busy signals (analog) or Q.931 messages indicating busy (digital).

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_REPLY, LINEDEVCAPS, lineGetDevCaps


lineSetTollList

The lineSetTollList function manipulates the toll list.

LONG lineSetTollList(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  LPCSTR lpszAddressIn,
  DWORD dwTollListOption
);

Parameters

hLineApp
The application handle returned by lineInitializeEx. If an application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL.
dwDeviceID
The device identifier for the line device upon which the call is intended to be dialed, so that variations in dialing procedures on different lines can be applied to the translation process.
lpszAddressIn
A pointer to a NULL-terminated ASCII string containing the address from which the prefix information is to be extracted for processing. This parameter must not be NULL, and it must be in the canonical address format.
dwTollListOption
The toll list operation to be performed. Only a single flag can be set. This parameter uses the following LINETOLLLISTOPTION_ constants:
LINETOLLLISTOPTION_ADD
Causes the prefix contained within the string pointed to by lpszAddressIn to be added to the toll list for the current location.
LINETOLLLISTOPTION_REMOVE
Causes the prefix to be removed from the toll list of the current location. If toll lists are not used or relevant to the country indicated in the current location, the operation has no affect.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INVALAPPHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INIFILECORRUPT, LINEERR_UNINITIALIZED, LINEERR_INVALLOCATION.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, lineInitializeEx


lineSetupConference

The lineSetupConference function sets up a conference call for the addition of the third party.

LONG lineSetupConference(
  HCALL hCall,
  HLINE hLine,
  LPHCALL lphConfCall,
  LPHCALL lphConsultCall,
  DWORD dwNumParties,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

hCall
The initial call that identifies the first party of a conference call. In some environments (as described in device capabilities), a call must exist to start a conference call, and the application must be an owner of this call. In other telephony environments, no call initially exists, hCall must be left NULL, and hLine must be specified to identify the line on which the conference call is to be initiated. The call state of hCall must be connected.
hLine
A handle to the line. This handle is used to identify the line device on which to originate the conference call if hCall is NULL. The hLine parameter is ignored if hCall is non-NULL.
lphConfCall
A pointer to an HCALL handle. This location is then loaded with a handle identifying the newly created conference call. The application is the initial sole owner of this call. The call state of hConfCall is not applicable.
lphConsultCall
A pointer to an HCALL handle. When setting up a call for the addition of a new party, a new temporary call (consultation call) is automatically allocated. Initially, the application is the sole owner for this call.
dwNumParties
The expected number of parties in the conference call. This number is passed to the service provider. The service provider is free to do as it pleases with this number: ignore it, use it as a hint to allocate the right size conference bridge inside the switch, and so on.
lpCallParams
A pointer to call parameters to be used when establishing the consultation call. This parameter can be set to NULL if no special call setup parameters are desired.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_BEARERMODEUNAVAIL, LINEERR_UNINITIALIZED, LINEERR_CALLUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_CONFERENCEFULL, LINEERR_INVALPOINTER, LINEERR_INUSE, LINEERR_INVALRATE, LINEERR_INVALADDRESSMODE, LINEERR_NOMEM, LINEERR_INVALBEARERMODE, LINEERR_NOTOWNER, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLPARAMS, LINEERR_RATEUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_STRUCTURETOOSMALL, LINEERR_USERUSERINFOTOOBIG.

Remarks

If LINEERR_INVALLINESTATE is returned, the line is currently not in a state in which this operation can be performed. A list of currently valid operations can be found in the dwLineFeatures member (of the type LINEFEATURE) in the LINEDEVSTATUS structure. (Calling lineGetLineDevStatus updates the information in LINEDEVSTATUS.) If LINEERR_INVALMEDIAMODE is returned, check for supported media modes on the line in the dwMediaModes member in the LINEDEVCAPS structure.

The lineSetupConference function provides two ways to establish a new conference call, depending on whether a normal two-party call is required to pre-exist or not. When setting up a conference call from an existing two-party call, the hCall parameter is a valid call handle that is initially added to the conference call by the lineSetupConference request; hLine is ignored. On switches where conference call setup does not start with an existing call, hCall must be NULL and hLine must be specified to identify the line device on which to initiate the conference call. In either case, a consultation call is allocated for connecting to the party that is to be added to the call. The application can then use lineDial to dial the address of the other party.

The conference call typically transitions into the onHoldPendingConference state, the consultation call into the dialtone state, and the initial call (if there is one) into the conferenced state.

A conference call can also be set up by a lineCompleteTransfer that is resolved into a three-way conference. The application may be able to toggle between the consultation call and the conference call using lineSwapHold.

A consultation call can be canceled by invoking lineDrop on it. When dropping a consultation call, the existing conference call typically transitions back to the connected state. The application should observe the LINE_CALLSTATE messages to determine exactly what happens to the calls. For example, if the conference call reverts back to a regular two-party call, the conference call becomes idle and the original participant call can revert to connected.

If an application specifies the handle of the original call (hCall) in a call to the lineUnhold function, both the conference call and the consultation call typically go to idle.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_CALLSTATE, lineCompleteTransfer, LINEDEVCAPS, LINEDEVSTATUS, lineDial, lineDrop, lineGetLineDevStatus, lineSwapHold, lineUnhold


lineSetupTransfer

The lineSetupTransfer function initiates a transfer of the call specified by the hCall parameter. It establishes a consultation call, lphConsultCall, on which the party can be dialed that can become the destination of the transfer. The application acquires owner privilege to the lphConsultCall parameter.

LONG lineSetupTransfer(
  HCALL hCall,
  LPHCALL lphConsultCall,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

hCall
The handle of the call to be transferred. The application must be an owner of the call. The call state of hCall must be connected.
lphConsultCall
A pointer to an hCall handle. This location is then loaded with a handle identifying the temporary consultation call. When setting up a call for transfer, a consultation call is automatically allocated that enables lineDial to dial the address associated with the new transfer destination of the call. The originating party can carry on a conversation over this consultation call prior to completing the transfer. The call state of hConsultCall is not applicable.

This transfer procedure may not be valid for some line devices. The application may need to ignore the new consultation call and unhold an existing held call (using lineUnhold) to identify the destination of the transfer. On switches that support cross-address call transfer, the consultation call can exist on a different address than the call to be transferred. It may also be necessary that the consultation call be set up as an entirely new call, by lineMakeCall, to the destination of the transfer. Which forms of transfer are available are specified in the call's address capabilities.

lpCallParams
A pointer to call parameters to be used when establishing the consultation call. This parameter can be set to NULL if no special call setup parameters are desired.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALRATE, LINEERR_CALLUNAVAIL, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_NOTOWNER, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALBEARERMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_RATEUNAVAIL, LINEERR_INVALCALLPARAMS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALLINESTATE, LINEERR_UNINITIALIZED, LINEERR_INVALMEDIAMODE, LINEERR_USERUSERINFOTOOBIG, LINEERR_INVALPOINTER.

Remarks

The lineSetupTransfer function sets up the transfer of the call specified by hCall. The setup phase of a transfer establishes a consultation call that enables the application to send the address of the destination (the party to be transferred to) to the switch, while the call to be transferred is kept on hold. This new call is referred to as a consultation call (hConsultCall) and can be dropped or otherwise manipulated independently of the original call.

When the consultation call has reached the dialtone call state, the application can proceed transferring the call either by dialing the destination address and tracking its progress, or by unholding an existing call. The transfer of the original call to the selected destination is completed using lineCompleteTransfer.

While the consultation call exists, the original call typically transitions to the onholdPendingTransfer state. The application may be able to toggle between the consultation call and the original call by using lineSwapHold. A consultation call can be canceled by invoking lineDrop on it. After dropping a consultation call, the original call typically transitions back to the connected state. If the call state of the original call is onHoldPendingTransfer, the lineUnhold function can be used to recover the call. In this case, the call state of the consultation call is set to idle.

The application can also transfer calls in a single step, without having to deal with the intervening consultation call, by using lineBlindTransfer.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_REPLY, lineBlindTransfer, lineCompleteTransfer, lineDial, lineDrop, lineMakeCall, lineSwapHold, lineUnhold


lineShutdown

The lineShutdown function shuts down the application's usage of the line abstraction of the API.

LONG lineShutdown(
  HLINEAPP hLineApp
);

Parameters

hLineApp
The application's usage handle for the line API.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Remarks

If this function is called when the application has lines open or calls active, the call handles are deleted and TAPI automatically performs the equivalent of a lineClose on each open line. However, it is recommended that applications explicitly close all open lines before invoking lineShutdown. If shutdown is performed while asynchronous requests are outstanding, those requests are canceled.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, lineClose


lineSwapHold

The lineSwapHold function swaps the specified active call with the specified call on consultation hold.

LONG lineSwapHold(
  HCALL hActiveCall,
  HCALL hHeldCall
);

Parameters

hActiveCall
The handle to the active call. The application must be an owner of the call. The call state of hActiveCall must be connected.
hHeldCall
The handle to the consultation call. The application must be an owner of the call. The call state of hHeldCall can be onHoldPendingTransfer, onHoldPendingConference, or onHold.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED.

Remarks

Swapping the active call with the call on consultation hold allows the application to alternate or toggle between these two calls. This is typical in call waiting.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_REPLY


lineTranslateAddress

The lineTranslateAddress function translates the specified address into another format.

LONG lineTranslateAddress(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  DWORD dwAPIVersion,
  LPCSTR lpszAddressIn,
  DWORD dwCard,
  DWORD dwTranslateOptions,
  LPLINETRANSLATEOUTPUT lpTranslateOutput
);

Parameters

hLineApp
The application handle returned by lineInitializeEx. If an application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL.
dwDeviceID
The device identifier for the line device upon which the call is intended to be dialed, so that variations in dialing procedures on different lines can be applied to the translation process.
dwAPIVersion
Indicates the highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on some particular line device).
lpszAddressIn
A pointer to a NULL-terminated ASCII string containing the address from which the information is to be extracted for translation. Must be in either the canonical address format, or an arbitrary string of dialable digits (non-canonical). This parameter must not be NULL. If the AddressIn contains a subaddress or name field, or additional addresses separated from the first address by ASCII CR and LF characters, only the first address is translated, and the remainder of the string is returned to the application without modification.
dwCard
The credit card to be used for dialing. This parameter is only valid if the CARDOVERRIDE bit is set in dwTranslateOptions. This parameter specifies the permanent identifier of a Card entry in the [Cards] section in the registry (as obtained from lineTranslateCaps) which should be used instead of the PreferredCardID specified in the definition of the CurrentLocation. It does not cause the PreferredCardID parameter of the current Location entry in the registry to be modified; the override applies only to the current translation operation. This parameter is ignored if the CARDOVERRIDE bit is not set in dwTranslateOptions.
dwTranslateOptions
The associated operations to be performed prior to the translation of the address into a dialable string. This parameter uses the following LINETRANSLATEOPTION_ constants:
LINETRANSLATEOPTION_CARDOVERRIDE
If this bit is set, dwCard specifies the permanent identifier of a Card entry in the [Cards] section in the registry (as obtained from lineTranslateCaps) that should be used instead of the PreferredCardID specified in the definition of the CurrentLocation. It does not cause the PreferredCardID parameter of the current Location entry in the registry to be modified; the override applies only to the current translation operation. The dwCard parameter is ignored if the CARDOVERRIDE bit is not set.
LINETRANSLATEOPTION_CANCELCALLWAITING
If a Cancel Call Waiting string is defined for the location, setting this bit causes that string to be inserted at the beginning of the dialable string. This is commonly used by data modem and fax applications to prevent interruption of calls by call waiting beeps. If no Cancel Call Waiting string is defined for the location, this bit has no affect.

Note If you have set the LINETRANSLATEOPTION_CANCELCALLWAITING bit, it is also advisable to set the LINECALLPARAMFLAGS_SECURE bit in the dwCallParamFlags member of the LINECALLPARAMS structure (passed in to lineMakeCall through the lpCallParams parameter). This prevents the line device from using dialable digits to suppress call interrupts.

LINETRANSLATEOPTION_FORCELOCAL
If the number is local but would have been translated as a long distance call (LINETRANSLATERESULT_INTOLLLIST bit set in the LINETRANSLATEOUTPUT structure), this option forces it to be translated as local. This is a temporary override of the toll list setting.
LINETRANSLATEOPTION_FORCELD
If the address could potentially have been a toll call, but would have been translated as a local call (LINETRANSLATERESULT_NOTINTOLLLIST bit set in the LINETRANSLATEOUTPUT structure), this option forces it to be translated as long distance. This is a temporary override of the toll list setting.
lpTranslateOutput
A pointer to an application-allocated memory area to contain the output of the translation operation, of type LINETRANSLATEOUTPUT. Prior to calling lineTranslateAddress, the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_INVALPOINTER, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NODRIVER, LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCARD, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPARAM.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, lineInitializeEx, LINECALLPARAMS, lineNegotiateAPIVersion, LINETRANSLATEOUTPUT


lineTranslateDialog

The lineTranslateDialog function displays an application-modal dialog box that allows the user to change the current location of a phone number about to be dialed, adjust location and calling card parameters, and see the effect.

LONG lineTranslateDialog(
  HLINEAPP hLineApp,
  DWORD dwDeviceID,
  DWORD dwAPIVersion,
  HWND hwndOwner,
  LPCSTR lpszAddressIn
);

Parameters

hLineApp
The application handle returned by lineInitializeEx. If an application has not yet called the lineInitializeEx function, it can set the hLineApp parameter to NULL.
dwDeviceID
The device identifier for the line device upon which the call is intended to be dialed, so that variations in dialing procedures on different lines can be applied to the translation process.
dwAPIVersion
Indicates the highest version of TAPI supported by the application (not necessarily the value negotiated by lineNegotiateAPIVersion on the line device indicated by dwDeviceID).
hwndOwner
A handle to a window to which the dialog box is to be attached. Can be a NULL value to indicate that any window created during the function should have no owner window.
lpszAddressIn
A pointer to a NULL-terminated ASCII string containing a phone number that is used, in the lower portion of the dialog box, to show the effect of the user's changes on the location parameters. The number must be in canonical format; if noncanonical, the phone number portion of the dialog box is not displayed. This pointer can be left NULL, in which case the phone number portion of the dialog box is not displayed. If the lpszAddressIn parameter contains a subaddress or name field, or additional addresses separated from the first address by ASCII CR and LF characters, only the first address is used in the dialog box.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_INVALPARAM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_INVALPOINTER, LINEERR_INIFILECORRUPT, LINEERR_NODRIVER, LINEERR_INUSE, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_INVALAPPHANDLE, LINEERR_OPERATIONFAILED.

Remarks

In TAPI version 2.0 or later, it is possible for multiple instances of this dialog box to be opened. In TAPI versions earlier than 2.0, LINEERR_INUSE is returned if the dialog box is already displayed by another application (cannot be open more than once). In these versions, TAPI brings the existing dialog box to the front, and the error indicates that any particulars related to the address passed in by the current application have not been handled, because that address was not processed by the function.

The application must call lineGetTranslateCaps after this function to obtain any changes the user made to the telephony address translation parameters, and call lineTranslateAddress to obtain a dialable string based on the user's new selections.

If any function related to address translation (for example, lineGetTranslateCaps or lineTranslateAddress) returns LINEERR_INIFILECORRUPT, the application should call lineTranslateDialog. The lineTranslateDialog function detects the errors and corrects them, and reports the action taken to the user. LINEERR_INIFILECORRUPT is returned the first time any of these functions are used after installation of Windows 95, because the parameters are uninitialized (lineTranslateDialog takes care of initializing them, using the user-specified default country to select the default country code).

Although this is a new function which older applications would not be expected to call, for backward compatibility they should not be prevented from doing so; the full range of API versions supported by TAPI (0x00010003 to 0x00010004) should work the same way.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Basic Telephony Services Reference, lineGetTranslateCaps, lineInitializeEx, lineNegotiateAPIVersion, lineTranslateAddress


lineUncompleteCall

The lineUncompleteCall function cancels the specified call completion request on the specified line.

LONG lineUncompleteCall(
  HLINE hLine,
  DWORD dwCompletionID
);

Parameters

hLine
A handle to the line device on which a call completion is to be canceled.
dwCompletionID
The completion identifier for the request that is to be canceled.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCOMPLETIONID, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_OPERATIONUNAVAIL.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_REPLY


lineUnhold

The lineUnhold function retrieves the specified held call.

LONG lineUnhold(
  HCALL hCall
);

Parameters

hCall
The handle to the call to be retrieved. The application must be an owner of this call. The call state of hCall must be onHold, onHoldPendingTransfer, or onHoldPendingConference.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_NOTOWNER, LINEERR_UNINITIALIZED.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_REPLY


lineUnpark

The lineUnpark function retrieves the call parked at the specified address and returns a call handle for it.

LONG lineUnpark(
  HLINE hLine,
  DWORD dwAddressID,
  LPHCALL lphCall,
  LPCSTR lpszDestAddress
);

Parameters

hLine
A handle to the open line device on which a call is to be unparked.
dwAddressID
The address on hLine at which the unpark is to be originated.
lphCall
A pointer to the location of type HCALL where the handle to the unparked call is returned. This handle is unrelated to any other handle which might have been previously associated with the retrieved call, such as the handle that might have been associated with the call when it was originally parked. The application is the initial sole owner of this call.
lpszDestAddress
A pointer to a NULL-terminated character buffer that contains the address where the call is parked. The address is in standard dialable address format.

Return Values

Returns a positive request identifier if the function is completed asynchronously, or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

LINEERR_INVALADDRESS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Line Services Functions, LINE_REPLY


Phone Device Functions

This section contains an alphabetic listing of the TAPI functions for phone devices.

For a categorization of TAPI functions by service level and task, see TAPI Quick Function Reference.


phoneCallbackFunc

The phoneCallbackFunc function is a placeholder for the application-supplied function name.

VOID FAR PASCAL phoneCallbackFunc(
  HANDLE hDevice,
  DWORD dwMsg,
  DWORD dwCallbackInstance,
  DWORD dwParam1,
  DWORD dwParam2,
  DWORD dwParam3
);

Parameters

hDevice
A handle to a phone device associated with the callback.
dwMsg
A line or call device message.
dwCallbackInstance
Callback instance data passed back to the application in the callback. This DWORD is not interpreted by TAPI.
dwParam1
A parameter for the message.
dwParam2
A parameter for the message.
dwParam3
A parameter for the message.

Remarks

For more information about the parameters passed to this callback function, see TAPI Messages.

All callbacks occur in the application's context. The callback function must reside in a dynamic-link library (DLL) or application module and be exported in the module-definition file.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with user-defined.


phoneClose

The phoneClose function closes the specified open phone device.

LONG phoneClose(
  HPHONE hPhone
);

Parameters

hPhone
A handle to the open phone device to be closed. If the function succeeds, the handle is no longer valid.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_OPERATIONFAILED, PHONEERR_RESOURCEUNAVAIL, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED.

Remarks

After the open phone device has been successfully closed, the implementation sends a PHONE_CLOSE message to the application. These messages can also be sent unsolicited as a result of the phone device being reclaimed somehow. An application should therefore be prepared to handle these unsolicited close messages. At the time the phone device is closed, any outstanding asynchronous replies are suppressed.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONE_CLOSE


phoneConfigDialog

The phoneConfigDialog function causes the provider of the specified phone device to display a modal dialog box (attached to the application's hwndOwner parameter) that allows the user to configure parameters related to the phone device specified by dwDeviceID.

LONG phoneConfigDialog(
  DWORD dwDeviceID,
  HWND hwndOwner,
  LPCSTR lpszDeviceClass
);

Parameters

dwDeviceID
The phone device to be configured.
hwndOwner
A handle to a window to which the dialog box is to be attached. Can be a NULL value to indicate that any window created during the function should have no owner window.
lpszDeviceClass
A pointer to a NULL-terminated string that identifies a device class name. This device class allows the application to select a specific subscreen of configuration information applicable to that device class. This parameter is optional and can be left NULL or empty, in which case the highest level configuration is selected.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_BADDEVICEID, PHONEERR_NOMEM, PHONEERR_INUSE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPARAM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALDEVICECLASS, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_UNINITIALIZED, PHONEERR_NODEVICE.

Remarks

The lpszDeviceClass parameter allows the application to select a specific subscreen of configuration information applicable to the device class in which the user is interested; the permitted strings are the same as for phoneGetID. For example, if the phone supports the wave API, passing "wave/in" as lpszDeviceClass would cause the provider to display the parameters related specifically to wave (or at least to start at the corresponding point in a multilevel configuration dialog box chain, eliminating the need to search for relevant parameters).

The lpszDeviceClass parameter should be "tapi/phone", "", or NULL to cause the provider to display the highest level configuration for the phone.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, phoneGetID


phoneDevSpecific

The phoneDevSpecific function is used as a general extension mechanism to enable a Telephony API implementation to provide features not described in the other TAPI functions. The meanings of these extensions are device specific.

LONG phoneDevSpecific(
  HPHONE hPhone,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

hPhone
A handle to a phone device.
lpParams
A pointer to a memory area used to hold a parameter block. Its interpretation is device specific. The contents of the parameter block are passed unchanged to or from the service provider by TAPI.
dwSize
The size in bytes of the parameter block area.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONFAILED.

Additional return values are device specific.

Remarks

This operation provides a generic parameter profile. The interpretation of the parameter block is device specific. Indications and replies that are device specific should use the PHONE_DEVSPECIFIC message.

A service provider can provide access to device-specific functions by defining parameters for use with this operation. Applications that want to make use of these device-specific extensions should consult the device-specific (vendor-specific) documentation that describes which extensions are defined. Typicaly, an application that relies on these device-specific extensions is not portable to work with other service-provider environments.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Extended Telephony Services Reference, PHONE_DEVSPECIFIC, PHONE_REPLY


phoneGetButtonInfo

The phoneGetButtonInfo function returns information about the specified button.

LONG phoneGetButtonInfo(
  HPHONE hPhone,
  DWORD dwButtonLampID,
  LPPHONEBUTTONINFO lpButtonInfo
);

Parameters

hPhone
A handle to the open phone device.
dwButtonLampID
A button on the phone device.
lpButtonInfo
A pointer to a variably sized structure of type PHONEBUTTONINFO. This data structure describes the mode and the function, and provides additional descriptive text corresponding to the button.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALBUTTONLAMPID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_STRUCTURETOOSMALL, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONEBUTTONINFO


phoneGetData

The phoneGetData function uploads the information from the specified location in the open phone device to the specified buffer.

LONG phoneGetData(
  HPHONE hPhone,
  DWORD dwDataID,
  LPVOID lpData,
  DWORD dwSize
);

Parameters

hPhone
A handle to the open phone device.
dwDataID
Where in the phone device the buffer is to be uploaded from.
lpData
A pointer to the memory buffer where the data is to be uploaded.
dwSize
The size of the data buffer in bytes.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALDATAID, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

Remarks

The function uploads a maximum of dwSize bytes from the phone device into the memory area pointed to by lpData. If dwSize is zero, nothing is copied. The size of each data area is listed in the phone's device capabilities.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions


phoneGetDevCaps

The phoneGetDevCaps function queries a specified phone device to determine its telephony capabilities.

LONG phoneGetDevCaps(
  HPHONEAPP hPhoneApp,
  DWORD dwDeviceID,
  DWORD dwAPIVersion,
  DWORD dwExtVersion,
  LPPHONECAPS lpPhoneCaps
);

Parameters

hPhoneApp
The handle to the application's registration with TAPI.
dwDeviceID
The phone device to be queried.
dwAPIVersion
The version number of the Telephony API to be used. The high-order word contains the major version number; the low-order word contains the minor version number. This number is obtained with the function phoneNegotiateAPIVersion.
dwExtVersion
The version number of the service provider-specific extensions to be used. This number is obtained with the function phoneNegotiateExtVersion. It can be left zero if no device-specific extensions are to be used. Otherwise, the high-order word contains the major version number; the low-order word contains the minor version number.
lpPhoneCaps
A pointer to a variably sized structure of type PHONECAPS. Upon successful completion of the request, this structure is filled with phone device capabilities information.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALAPPHANDLE, PHONEERR_INVALPOINTER, PHONEERR_BADDEVICEID, PHONEERR_OPERATIONFAILED, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_NOMEM, PHONEERR_STRUCTURETOOSMALL, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NODRIVER, PHONEERR_UNINITIALIZED, PHONEERR_NODEVICE.

Remarks

Before using phoneGetDevCaps, the application must negotiate the TAPI version number to use, and optionally, the extension version to use.

TAPI and extension version numbers are those under which TAPI, Telephony DLL, and service provider must operate. If version ranges do not overlap, the application and API or service-provider versions are incompatible and an error is returned.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONECAPS, phoneNegotiateAPIVersion, phoneNegotiateExtVersion


phoneGetDisplay

The phoneGetDisplay function returns the current contents of the specified phone display.

LONG phoneGetDisplay(
  HPHONE hPhone,
  LPVARSTRING lpDisplay
);

Parameters

hPhone
A handle to the open phone device.
lpDisplay
A pointer to the memory location where the display content is to be stored, of type VARSTRING.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_STRUCTURETOOSMALL, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED, PHONEERR_NOMEM.

Remarks

The lpDisplay memory area should be at least (dwDisplayNumRows * dwDisplayNumColumns) elements in size to receive all of the display information. The dwDisplayNumRows and dwDisplayNumColumns members are available in the PHONECAPS structure returned by phoneGetDevCaps.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONECAPS, phoneGetDevCaps, VARSTRING


phoneGetGain

The phoneGetGain function returns the gain setting of the microphone of the specified phone's hookswitch device.

LONG phoneGetGain(
  HPHONE hPhone,
  DWORD dwHookSwitchDev,
  LPDWORD lpdwGain
);

Parameters

hPhone
A handle to the open phone device.
dwHookSwitchDev
The hookswitch device whose gain level is queried. The dwHookSwitchDev parameter can have only one bit set. This parameter uses the following PHONEHOOKSWITCHDEV_ constants:
PHONEHOOKSWITCHDEV_HANDSET
The phone's handset.
PHONEHOOKSWITCHDEV_SPEAKER
The phone's speakerphone or adjunct.
PHONEHOOKSWITCHDEV_HEADSET
The phone's headset.
lpdwGain
A pointer to a DWORD-sized location containing the current gain setting of the hookswitch microphone component. The dwGain parameter specifies the volume level of the hookswitch device. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of gain settings in this range are service provider-specific.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions


phoneGetHookSwitch

The phoneGetHookSwitch function returns the current hookswitch mode of the specified open phone device.

LONG phoneGetHookSwitch(
  HPHONE hPhone,
  LPDWORD lpdwHookSwitchDevs
);

Parameters

hPhone
A handle to the open phone device.
lpdwHookSwitchDevs
A pointer to a DWORD-sized location to be filled with the mode of the phone's hookswitch devices. If a bit position is FALSE, the corresponding hookswitch device is onhook; if TRUE, the microphone and/or speaker part of the corresponding hookswitch device is offhook. To find out whether the microphone and/or speaker are enabled, the application can use phoneGetStatus. This parameter uses the following PHONEHOOKSWITCHDEV_ constants:
PHONEHOOKSWITCHDEV_HANDSET
The phone's handset.
PHONEHOOKSWITCHDEV_SPEAKER
The phone's speakerphone or adjunct.
PHONEHOOKSWITCHDEV_HEADSET
The phone's headset.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED.

Remarks

After the hookswitch state of a device changes, and if hookswitch monitoring is enabled, the application is sent a PHONE_STATE message.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONE_STATE, phoneGetStatus


phoneGetIcon

The phoneGetIcon function allows an application to retrieve a service phone device-specific (or provider-specific) icon that can be displayed to the user.

LONG phoneGetIcon(
  DWORD dwDeviceID,
  LPCSTR lpszDeviceClass,
  LPHICON lphIcon
);

Parameters

dwDeviceID
The phone device whose icon is requested.
lpszDeviceClass
A pointer to a NULL-terminated string that identifies a device class name. This device class allows the application to select a specific sub-icon applicable to that device class. This parameter is optional and can be left NULL or empty, in which case the highest-level icon associated with the phone device rather than a specified media stream device would be selected.
lphIcon
A pointer to a memory location in which the handle to the icon is returned.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_BADDEVICEID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALDEVICECLASS, PHONEERR_UNINITIALIZED, PHONEERR_NOMEM, PHONEERR_NODEVICE.

Remarks

The phoneGetIcon function causes the provider to return a handle (in lphIcon) to an icon resource (obtained from LoadIcon) associated with the specified phone. The icon handle is for a resource associated with the provider; the application must use CopyIcon if it wants to reference the icon after the provider is unloaded, which is unlikely to happen as long as the application has the phone open.

The lpszDeviceClass parameter allows the provider to return different icons based on the type of service being referenced by the caller. The permitted strings are the same as for phoneGetID. For example, if the phone supports the Comm API, passing "COMM" as lpszDeviceClass causes the provider to return an icon related specifically to the Comm device functions of the service provider. The parameters "tapi/phone", "", or NULL can be used to request the icon for the phone service.

For applications using a TAPI version earlier than 2.0, if the provider does not return an icon (whether because the given device class is invalid or the provider does not support icons), TAPI substitutes a generic Win32 Telephony phone device icon. For applications using TAPI version 2.0 or later, TAPI substitutes the default phone icon only if the lpszDeviceClass parameter is "tapi/phone", "", or NULL. For any other device class, if the given device class is not valid or the provider does not support icons for the class, phoneGetIcon returns PHONEERR_INVALDEVICECLASS.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, phoneGetID


phoneGetID

The phoneGetID function returns a device identifier for the given device class associated with the specified phone device.

LONG phoneGetID(
  HPHONE hPhone,
  LPVARSTRING lpDeviceID,
  LPCSTR lpszDeviceClass
);

Parameters

hPhone
A handle to an open phone device.
lpDeviceID
A pointer to a data structure of type VARSTRING where the device identifier is returned. Upon successful completion of the request, this location is filled with the device identifier. The format of the returned information depends on the method used by the device class (API) for naming devices.
lpszDeviceClass
A pointer to a NULL-terminated string that specifies the device class of the device whose identifier is requested. Valid device class strings are those used in the system.ini section to identify device classes.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALDEVICECLASS, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONFAILED, PHONEERR_STRUCTURETOOSMALL, PHONEERR_OPERATIONUNAVAIL.

Remarks

The phoneGetID function can be used to retrieve a phone device identifier given a phone handle. It can also be used to obtain the device identifier of the media device (for device classes such as COM, wave, MIDI, phone, line, or NDIS) associated with the opened phone device. The names of these device class are not case sensitive. This identifier can then be used with the appropriate media API to select the corresponding device.

See Device Classes in TAPI for device class names.

A vendor that defines a device-specific media mode also needs to define the corresponding device-specific (proprietary) API to manage devices of the media mode. To avoid collisions on device class names assigned independently by different vendors, a vendor should select a name that uniquely identifies both the vendor and, following it, the media type. For example: "intel/video".

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, VARSTRING


phoneGetLamp

The phoneGetLamp function returns the current lamp mode of the specified lamp.

LONG phoneGetLamp(
  HPHONE hPhone,
  DWORD dwButtonLampID,
  LPDWORD lpdwLampMode
);

Parameters

hPhone
A handle to the open phone device.
dwButtonLampID
The identifier of the lamp to be queried.
lpdwLampMode
A pointer to a memory location that holds the lamp mode status of the given lamp. The lpdwLampMode parameter can have at most one bit set. This parameter uses the following PHONELAMPMODE_ constants:
PHONELAMPMODE_BROKENFLUTTER
Broken flutter is the superposition of flash and flutter.
PHONELAMPMODE_FLASH
Flash means slow on and off.
PHONELAMPMODE_FLUTTER
Flutter means fast on and off.
PHONELAMPMODE_OFF
The lamp is off.
PHONELAMPMODE_STEADY
The lamp is continuously lit.
PHONELAMPMODE_WINK
The lamp is winking.
PHONELAMPMODE_UNKNOWN
The lamp mode is currently unknown.
PHONELAMPMODE_DUMMY
This value is used to describe a button/lamp position that has no corresponding lamp.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALBUTTONLAMPID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

Remarks

Phone sets that have multiple lamps per button should be modeled using multiple button/lamp pairs. Each extra button/lamp pair should use a DUMMY button.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions


phoneGetMessage

The phoneGetMessage function returns the next TAPI message that is queued for delivery to an application that is using the Event Handle notification mechanism (see phoneInitializeEx for further details).

LONG phoneGetMessage(
  HPHONEAPP hPhoneApp,
  LPPHONEMESSAGE lpMessage,
  DWORD dwTimeout
);

Parameters

hPhoneApp
The handle returned by phoneInitializeEx. The application must have set the PHONEINITIALIZEEXOPTION_USEEVENT option in the dwOptions member of the PHONEINITIALIZEEXPARAMS structure.
lpMessage
A pointer to a PHONEMESSAGE structure. Upon successful return from this function, the structure contains the next message that had been queued for delivery to the application.
dwTimeout
The time-out interval, in milliseconds. The function returns if the interval elapses, even if no message can be returned. If dwTimeout is zero, the function checks for a queued message and returns immediately. If dwTimeout is INFINITE, the function's time-out interval never elapses.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALAPPHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPOINTER, PHONEERR_NOMEM.

Remarks

If this function has been called with a nonzero timeout and the application calls phoneShutdown on another thread, this function returns immediately with PHONEERR_INVALAPPHANDLE.

If the timeout expires (or was zero) and no message could be fetched from the queue, the function returns with the error PHONEERR_OPERATIONFAILED.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

phoneInitializeEx, PHONEINITIALIZEEXPARAMS, PHONEMESSAGE, phoneShutdown


phoneGetRing

The phoneGetRing function enables an application to query the specified open phone device as to its current ring mode.

LONG phoneGetRing(
  HPHONE hPhone,
  LPDWORD lpdwRingMode,
  LPDWORD lpdwVolume
);

Parameters

hPhone
A handle to the open phone device.
lpdwRingMode
The ringing pattern with which the phone is ringing. Zero indicates that the phone is not ringing.
lpdwVolume
The volume level with which the phone is ringing. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service provider-specific.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPHONESTATE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED.

Remarks

The service provider defines the actual audible ringing patterns corresponding to each of the phone's ring modes.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions


phoneGetStatus

The phoneGetStatus function enables an application to query the specified open phone device for its overall status.

LONG phoneGetStatus(
  HPHONE hPhone,
  LPPHONESTATUS lpPhoneStatus
);

Parameters

hPhone
A handle to the open phone device to be queried.
lpPhoneStatus
A pointer to a variably sized data structure of type PHONESTATUS, which is loaded with the returned information about the phone's status.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_OPERATIONFAILED, PHONEERR_STRUCTURETOOSMALL, PHONEERR_OPERATIONUNAVAIL, PHONEERR_UNINITIALIZED.

Remarks

An application can use this function to determine the current state of an open phone device. The status information describes information about the phone device's hookswitch devices, ringer, volume, display, and lamps.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONESTATUS


phoneGetStatusMessages

The phoneGetStatusMessages function returns which phone-state changes on the specified phone device generate a callback to the application.

LONG phoneGetStatusMessages(
  HPHONE hPhone,
  LPDWORD lpdwPhoneStates,
  LPDWORD lpdwButtonModes,
  LPDWORD lpdwButtonStates
);

Parameters

hPhone
A handle to the open phone device to be monitored.
lpdwPhoneStates
A pointer to a PHONESTATE_ constant. These flags specify the set of phone status changes and events for which the application can receive notification messages. The lpdwPhoneStates parameter can return a value with zero, one, or multiple bits set. Monitoring can be individually enabled and disabled for:
PHONESTATE_OTHER
Phone-status items other than those listed below have changed. The application should check the current phone status to determine which items have changed.
PHONESTATE_CONNECTED
The connection between the phone device and TAPI was just made. This happens when TAPI is first invoked or when the wire connecting the phone to the computer is plugged in while TAPI is active.
PHONESTATE_DISCONNECTED
The connection between the phone device and TAPI was just broken. This happens when the wire connecting the phone set to the computer is unplugged while TAPI is active.
PHONESTATE_OWNER
The number of owners for the phone device has changed.
PHONESTATE_MONITORS
The number of monitors for the phone device has changed.
PHONESTATE_DISPLAY
The display of the phone has changed.
PHONESTATE_LAMP
A lamp of the phone has changed.
PHONESTATE_RINGMODE
The ring mode of the phone has changed.
PHONESTATE_RINGVOLUME
The ring volume of the phone has changed.
PHONESTATE_HANDSETHOOKSWITCH
The handset's hookswitch state has changed.
PHONESTATE_HANDSETVOLUME
The handset's speaker volume setting has changed.
PHONESTATE_HANDSETGAIN
The handset's microphone gain setting has changed.
PHONESTATE_SPEAKERHOOKSWITCH
The speakerphone's hookswitch state has changed.
PHONESTATE_SPEAKERVOLUME
The speakerphone's speaker volume setting has changed.
PHONESTATE_SPEAKERGAIN
The speakerphone's microphone gain setting state has changed.
PHONESTATE_HEADSETHOOKSWITCH
The headset's hookswitch state has changed.
PHONESTATE_HEADSETVOLUME
The headset's speaker volume setting has changed.
PHONESTATE_HEADSETGAIN
The headset's microphone gain setting has changed.
PHONESTATE_SUSPEND
The application's use of the phone is temporarily suspended.
PHONESTATE_RESUME
The application's use of the phone device is resumed after having been suspended for some time.
PHONESTATE_DEVSPECIFIC
The phone's device-specific information has changed.
PHONESTATE_REINIT
Items have changed in the configuration of phone devices. To become aware of these changes (as with the appearance of new phone devices) the application should reinitialize its use of TAPI. The hDevice parameter of the PHONE_STATE message is left NULL for this state change, as it applies to any of the phones in the system.
PHONESTATE_CAPSCHANGE
Indicates that, due to configuration changes made by the user or other circumstances, one or more of the members in the PHONECAPS structure have changed. The application should use phoneGetDevCaps to read the updated structure. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version receive PHONE_STATE messages specifying PHONESTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI in order to obtain the updated information.
PHONESTATE_REMOVED
Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A PHONE_STATE message with this value is normally immediately followed by a PHONE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized result in PHONEERR_NODEVICE being returned to the application. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous TAPI version do not receive any notification.
lpdwButtonModes
A pointer to flags that specify the set of phone-button modes for which the application can receive notification messages. The lpdwButtonModes parameter can return a value with zero, one, or multiple bits set. This parameter uses the following PHONEBUTTONMODE_ constants:
PHONEBUTTONMODE_CALL
The button is assigned to a call appearance.
PHONEBUTTONMODE_FEATURE
The button is assigned to requesting features from the switch, such as hold, conference, and transfer.
PHONEBUTTONMODE_KEYPAD
The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'.
PHONEBUTTONMODE_LOCAL
The button is a local function button, such as mute or volume control.
PHONEBUTTONMODE_DISPLAY
The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.
lpdwButtonStates
A pointer to a DWORD-sized location that contains flags specifying the set of phone button state changes for which the application can receive notification messages. The lpdwButtonStates parameter can return a value with zero, one, or multiple bits set. This parameter uses the following PHONEBUTTONSTATE_ constants:
PHONEBUTTONSTATE_UP
The button is in the "up" state.
PHONEBUTTONSTATE_DOWN
The button is in the "down" state (pressed down).
PHONEBUTTONSTATE_UNKNOWN
Indicates that the up or down state of the button is not known at this time, but may become known at a future time.
PHONEBUTTONSTATE_UNAVAIL
Indicates that the up or down state of the button is not known to the service provider, and will not become known.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_OPERATIONFAILED, PHONEERR_UNINITIALIZED.

Remarks

An application can use phoneGetStatusMessages to query the generation of the corresponding messages. Message generation can be controlled by phoneSetStatusMessages. All phone status messages are disabled by default.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONE_CLOSE, PHONE_STATE, PHONECAPS, phoneGetDevCaps, phoneSetStatusMessages


phoneGetVolume

The phoneGetVolume function returns the volume setting of the specified phone's hookswitch device.

LONG phoneGetVolume(
  HPHONE hPhone,
  DWORD dwHookSwitchDev,
  LPDWORD lpdwVolume
);

Parameters

hPhone
A handle to the open phone device.
dwHookSwitchDev
A single hookswitch device whose volume level is queried. This parameter uses the following PHONEHOOKSWITCHDEV_ constants:
PHONEHOOKSWITCHDEV_HANDSET
The phone's handset.
PHONEHOOKSWITCHDEV_SPEAKER
The phone's speakerphone or adjunct.
PHONEHOOKSWITCHDEV_HEADSET
The phone's headset.
lpdwVolume
A pointer to a DWORD-sized location containing the current volume setting of the hookswitch device. The dwVolume parameter specifies the volume level of the hookswitch device. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service provider-specific.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPHONESTATE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions


phoneInitialize

The phoneInitialize function is obsolete. It continues to be exported by tapi.dll and tapi32.dll for backward compatibility with applications using TAPI versions 1.3 and 1.4.

Applications using TAPI version 2.0 or later must use phoneInitializeEx instead.

For Windows 95 applications only

The phoneIntialize function initializes the application's use of TAPI for the subsequent use of the phone functions in the Telephony API. It registers the application's specified notification mechanism and returns the number of phone devices that are available to the application.

LONG phoneInitialize(
  LPHPHONEAPP lphPhoneApp,
  HINSTANCE hInstance,
  PHONECALLBACK lpfnCallback,
  LPCSTR lpszAppName,
  LPDWORD lpdwNumDevs
);

Parameters

lphPhoneApp
A pointer to a location that is filled with the application's usage handle for TAPI.
hInstance
The instance handle of the client application or DLL.
lpfnCallback
The address of a callback function that is invoked to determine status and events on the phone device.
lpszAppName
A pointer to a NULL-terminated ASCII string that contains displayable characters. If this parameter is non-NULL, it contains an application-supplied name of the application. This name is provided in the PHONESTATUS structure to indicate, in a user-friendly way, which application is the current owner of the phone device. This information can be useful for logging and status reporting purposes. If lpszAppName is NULL, the application's filename is used instead.
lpdwNumDevs
A pointer to DWORD-sized memory location. This location is loaded with the number of phone devices available to the application.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALAPPNAME, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_NOMEM, PHONEERR_OPERATIONFAILED, PHONEERR_REINIT, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NODEVICE, PHONEERR_NODRIVER, PHONEERR_INVALPARAM

Remarks

The application can refer to individual phone devices by using phone device identifiers that range from zero to dwNumDevs minus one. An application should not assume that these phone devices are capable of anything beyond what is specified by the Assisted Telephony subset without first querying their device capabilities with the phoneGetDevCaps function.

Applications should not invoke phoneInitialize without subsequently opening a phone (at least for monitoring). If the application is not monitoring and not using any devices, it should call phoneShutdown so that memory resources allocated by TAPI can be released if unneeded, and TAPI itself can be unloaded from memory while not needed.

Another reason for performing a phoneShutdown is that if a user changes the device configuration (adds or removes a line or phone), there is no way for TAPI to notify an application that has a line or phone handle open at the time. After a reconfiguration has taken place, causing a PHONESTATE_REINIT message to be sent, no applications can open a device until all applications have performed a phoneShutdown.

If any service provider fails to initialize properly, the phoneInitialize function fails and returns the error indicated by the service provider. If the PHONEERR_INVALPARAM error value is returned, the specified hInstance parameter is invalid.

QuickInfo

Version: Use TAPI version 1.4. Not available in TAPI 2.0 or later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

phoneGetDevCaps, phoneInitializeEx, phoneShutdown, PHONESTATUS


phoneInitializeEx

The phoneInitializeEx function initializes the application's use of TAPI for subsequent use of the phone abstraction. It registers the application's specified notification mechanism and returns the number of phone devices available to the application. A phone device is any device that provides an implementation for the phone-prefixed functions in the Telephony API.

LONG phoneInitializeEx(
  LPHPHONEAPP lphPhoneApp,
  HINSTANCE hInstance,
  PHONECALLBACK lpfnCallback,
  LPCSTR lpszFriendlyAppName,
  LPDWORD lpdwNumDevs,
  LPDWORD lpdwAPIVersion,
  LPPHONEINITIALIZEEXPARAMS lpPhoneInitializeExParams
);

Parameters

lphPhoneApp
A pointer to a location that is filled with the application's usage handle for TAPI.
hInstance
The instance handle of the client application or DLL. The application or DLL can pass NULL for this parameter, in which case TAPI uses the module handle of the root executable of the process.
lpfnCallback
The address of a callback function that is invoked to determine status and events on the line device, addresses, or calls, when the application is using the "hidden window" method of event notification (for more information see phoneCallbackFunc). This parameter is ignored and should be set to NULL when the application chooses to use the "event handle" or "completion port" event notification mechanisms.
lpszFriendlyAppName
A pointer to a NULL-terminated ASCII string that contains only displayable ASCII characters. If this parameter is not NULL, it contains an application-supplied name for the application. This name is provided in the PHONESTATUS structure to indicate, in a user-friendly way, which application has ownership of the phone device. If lpszFriendlyAppName is NULL, the application's module filename is used instead (as returned by the Windows API GetModuleFileName).
lpdwNumDevs
A pointer to a DWORD-sized location. Upon successful completion of this request, this location is filled with the number of phone devices available to the application.
lpdwAPIVersion
A pointer to a DWORD-sized location. The application must initialize this DWORD, before calling this function, to the highest API version it is designed to support (for example, the same value it would pass into dwAPIHighVersion parameter of phoneNegotiateAPIVersion). Artificially high values must not be used; the value must be accurately set (for this release, to 0x00020000). TAPI translates any newer messages or structures into values or formats supported by the application's version. Upon successful completion of this request, this location is filled with the highest API version supported by TAPI (for this release, 0x00020000), thereby allowing the application to detect and adapt to having been installed on a system with an older version of TAPI.
lpPhoneInitializeExParams
A pointer to a structure of type PHONEINITIALIZEEXPARAMS containing additional parameters used to establish the association between the application and TAPI (specifically, the application's selected event notification mechanism and associated parameters).

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALAPPNAME, PHONEERR_OPERATIONFAILED, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_REINIT, PHONEERR_NOMEM, PHONEERR_INVALPARAM.

Remarks

Applications must select one of three mechanisms by which TAPI notifies the application of telephony events: Hidden Window, Event Handle, or Completion Port.

The Hidden Window mechanism is selected by specifying PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW in the dwOptions member in the PHONEINITIALIZEEXPARAMS structure. In this mechanism (which is the only mechanism available to TAPI version 1.x applications), TAPI creates a window in the context of the application during the phoneInitializeEx function, and subclasses the window so that all messages posted to it are handled by a WNDPROC in TAPI itself. When TAPI has a message to deliver to the application, TAPI posts a message to the hidden window. When the message is received (which can happen only when the application calls the Windows GetMessage API), Windows switches the process context to that of the application and invokes the WNDPROC in TAPI. TAPI then delivers the message to the application by calling the PhoneCallbackProc, a pointer to which the application provided as a parameter in its call to phoneInitializeEx (or phoneInitialize, for TAPI version 1.3 and 1.4 applications). This mechanism requires the application to have a message queue (which is not desirable for service processes) and to service that queue regularly to avoid delaying processing of telephony events. The hidden window is destroyed by TAPI during the phoneShutdown function.

The Event Handle mechanism is selected by specifying PHONEINITIALIZEEXOPTION_USEEVENT in the dwOptions member in the PHONEINITIALIZEEXPARAMS structure. In this mechanism, TAPI creates an event object on behalf of the application, and returns a handle to the object in the hEvent member in PHONEINITIALIZEEXPARAMS. The application must not manipulate this event in any manner (for example, must not call SetEvent, ResetEvent, CloseHandle, and so on) or undefined behavior results; the application can only wait on this event using functions such as WaitForSingleObject or MsgWaitForMultipleObjects. TAPI signals this event whenever a telephony event notification is pending for the application; the application must call phoneGetMessage to fetch the contents of the message. The event is reset by TAPI when no events are pending. The event handle is closed and the event object destroyed by TAPI during the phoneShutdown function. The application is not required to wait on the event handle that is created; the application could choose instead to call phoneGetMessage and have it block waiting for a message to be queued.

The Completion Port mechanism is selected by specifying PHONEINITIALIZEEXOPTION_USECOMPLETION PORT in the dwOptions member in the PHONEINITIALIZEEXPARAMS structure. In this mechanism, whenever a telephony event needs to be sent to the application, TAPI sends it to the application using PostQueuedCompletionStatus to the completion port that the application specified in the hCompletionPort member in PHONEINITIALIZEEXPARAMS, tagged with the completion key that the application specified in the dwCompletionKey member in PHONEINITIALIZEEXPARAMS. The application must have previously created the completion port using CreateIoCompletionPort. The applications retrieves events using GetQueuedCompletionStatus. Upon return from GetQueuedCompletionStatus, the application has the specified dwCompletionKey written to the DWORD pointed to by the lpCompletionKey parameter, and a pointer to a PHONEMESSAGE structure returned to the location pointed to by lpOverlapped. After the application has processed the event, the application must call LocalFree to release the memory used to contain the PHONEMESSAGE structure. Because the application created the completion port (thereby allowing it to be shared for other purposes), the application must close it; the application must not close the completion port until after calling phoneShutdown.

When a multithreaded application is using the Event Handle mechanism and more than one thread is waiting on the handle, or the Completion Port notification mechanism and more than one thread is waiting on the port, it is possible for telephony events to be processed out of sequence. This is not due to the sequence of delivery of events from TAPI, but would be caused by the time slicing of threads or the execution of threads on separate processors.

If PHONEERR_REINIT is returned and TAPI reinitialization has been requested (for example, as a result of adding or removing a telephony service provider), then phoneInitializeEx requests are rejected with this error until the last application shuts down its usage of the API (using phoneShutdown). At that time, the new configuration becomes effective and applications are once again permitted to call phoneInitializeEx.

If the PHONEERR_INVALPARAM error value is returned, the specified hInstance parameter is invalid.

The application can refer to individual phone devices by using phone device identifiers that range from zero to dwNumDevs minus one. An application should not assume that these phone devices are capable of any particular TAPI function without first querying their device capabilities by phoneGetDevCaps.

For information about the listing of service dependencies, see Service Dependencies.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, phoneCallbackFunc, phoneGetDevCaps, phoneGetMessage, PHONEINITIALIZEEXPARAMS, PHONEMESSAGE, phoneNegotiateAPIVersion, phoneShutdown, PHONESTATUS


phoneNegotiateAPIVersion

The phoneNegotiateAPIVersion allows an application to negotiate an API version to use for the specified phone device.

LONG phoneNegotiateAPIVersion(
  HPHONEAPP hPhoneApp,
  DWORD dwDeviceID,
  DWORD dwAPILowVersion,
  DWORD dwAPIHighVersion,
  LPDWORD lpdwAPIVersion,
  LPPHONEEXTENSIONID lpExtensionID
);

Parameters

hPhoneApp
The handle to the application's registration with TAPI.
dwDeviceID
The phone device to be queried.
dwAPILowVersion
The least recent API version the application is compliant with. The high-order word is the major version number, the low-order word is the minor version number.
dwAPIHighVersion
The most recent API version the application is compliant with. The high-order word is the major version number, the low-order word is the minor version number.
lpdwAPIVersion
A pointer to a DWORD-sized location that contains the API version number that was negotiated. If negotiation succeeds, this number is in the range dwAPILowVersion to dwAPIHighVersion.
lpExtensionID
A pointer to a structure of type PHONEEXTENSIONID. If the service provider for the specified dwDeviceID parameter supports provider-specific extensions, this structure is filled with the extension identifier of these extensions when negotiation succeeds. This structure contains all zeros if the line provides no extensions. An application can ignore the returned parameter if it does not use extensions.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALAPPHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_BADDEVICEID, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NODRIVER, PHONEERR_NOMEM, PHONEERR_INVALPOINTER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_UNINITIALIZED, PHONEERR_NODEVICE.

Remarks

The phoneNegotiateAPIVersion function is used to negotiate the API version number to use with the specified phone device. It returns the extension identifier supported by the phone device, or zeros if no extensions are provided.

If the application wants to use the extensions defined by the returned extension identifier, it must call phoneNegotiateExtVersion to negotiate the extension version to use.

Use phoneInitializeEx to determine the number of phone devices present in the system. The device identifier specified by dwDeviceID varies from zero to one less than the number of phone devices present.

The API version number negotiated is that under which TAPI can operate. If version ranges do not overlap, the application, API, or service-provider versions are incompatible and an error is returned.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONEEXTENSIONID, phoneInitializeEx, phoneNegotiateExtVersion


phoneNegotiateExtVersion

The phoneNegotiateExtVersion function allows an application to negotiate an extension version to use with the specified phone device. This operation need not be called if the application does not support extensions.

LONG phoneNegotiateExtVersion(
  HPHONEAPP hPhoneApp,
  DWORD dwDeviceID,
  DWORD dwAPIVersion,
  DWORD dwExtLowVersion,
  DWORD dwExtHighVersion,
  LPDWORD lpdwExtVersion
);

Parameters

hPhoneApp
The handle to the application's registration with TAPI.
dwDeviceID
The phone device to be queried.
dwAPIVersion
The API version number that was negotiated for the specified phone device using phoneNegotiateAPIVersion.
dwExtLowVersion
The least recent extension version of the extension identifier returned by phoneNegotiateAPIVersion that the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.
dwExtHighVersion
The most recent extension version of the extension identifier returned by phoneNegotiateAPIVersion that the application is compliant with. The high-order word is the major version number; the low-order word is the minor version number.
lpdwExtVersion
A pointer to a DWORD-sized location that contains the extension version number that was negotiated. If negotiation succeeds, this number is in the range dwExtLowVersion to dwExtHighVersion.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALAPPHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_BADDEVICEID, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NODRIVER, PHONEERR_NOMEM, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_UNINITIALIZED, PHONEERR_INVALPOINTER, PHONEERR_NODEVICE.

Remarks

The phoneNegotiateAPIVersion function is used to negotiate the API version number to use. It returns the extension identifier supported by the phone device, or zeros if no extensions are provided.

In order for the application to use the extensions defined by the returned extension identifier, it must call phoneNegotiateExtVersion to negotiate the extension version to use.

Use phoneInitializeEx to determine the number of phone devices present in the system. The device identifier specified by dwDeviceID varies from zero to one less than the number of phone devices present.

The extension version number negotiated is that under which the application and service provider must both operate. If version ranges do not overlap, the application and service-provider versions are incompatible and an error is returned.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Extended Telephony Services Reference, phoneInitializeEx, phoneNegotiateAPIVersion


phoneOpen

The phoneOpen function opens the specified phone device. A phone device can be opened using either owner privilege or monitor privilege. An application that opens the phone with owner privilege can control the phone's lamps, display, ringer, and hookswitch or hookswitches. An application that opens the phone device with monitor privilege is notified only about events that occur at the phone, such as hookswitch changes or button presses. Ownership of a phone device is exclusive. In other words, only one application can have a phone device opened with owner privilege at a time. The phone device can, however, be opened multiple times with monitor privilege.

LONG phoneOpen(
  HPHONEAPP hPhoneApp,
  DWORD dwDeviceID,
  LPHPHONE lphPhone,
  DWORD dwAPIVersion,
  DWORD dwExtVersion,
  DWORD dwCallbackInstance,
  DWORD dwPrivilege
);

Parameters

hPhoneApp
A handle to the application's registration with TAPI.
dwDeviceID
The phone device to be opened.
lphPhone
A pointer to an HPHONE handle that identifies the open phone device. Use this handle to identify the device when invoking other phone control functions.
dwAPIVersion
The API version number under which the application and Telephony API have agreed to operate. This number is obtained from phoneNegotiateAPIVersion.
dwExtVersion
The extension version number under which the application and the service provider agree to operate. This number is zero if the application does not use any extensions. This number is obtained from phoneNegotiateExtVersion.
dwCallbackInstance
User instance data passed back to the application with each message. This parameter is not interpreted by the Telephony API.
dwPrivilege
The privilege requested. The dwPrivilege parameter can have only one bit set. This parameter uses the following PHONEPRIVILEGE_ constants:
PHONEPRIVILEGE_MONITOR
An application that opens a phone device with this privilege is informed about events and state changes occurring on the phone. The application cannot invoke any operations on the phone device that would change its state.
PHONEPRIVILEGE_OWNER
An application that opens a phone device in this mode is allowed to change the state of the lamps, ringer, display, and hookswitch devices of the phone. Having owner privilege to a phone device automatically includes monitor privilege as well.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_ALLOCATED, PHONEERR_NODRIVER, PHONEERR_BADDEVICEID, PHONEERR_NOMEM, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_OPERATIONFAILED, PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALAPPHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_UNINITIALIZED, PHONEERR_INVALPRIVILEGE, PHONEERR_REINIT, PHONEERR_INUSE, PHONEERR_NODEVICE, PHONEERR_INIFILECORRUPT.

Remarks

When opening a phone device with monitor privileges, the application is sent messages when events occur that change the status of the phone. Messages sent to the application include PHONE_BUTTON and PHONE_STATE. The latter provides an indication of the phone's status item that has changed.

When opening a phone with owner privilege, the phone device can be manipulated in ways that affect the state of the phone device. An application should only open a phone using owner privilege if it actively wants to manipulate the phone device, and it should close the phone device when finished to allow other applications to control the phone.

When an application opens a phone device, it must specify the negotiated API version and, if it wants to use the phone's extensions, the phone's device-specific extension version. This version number should have been obtained with the phoneNegotiateAPIVersion and phoneNegotiateExtVersion functions. Version numbering allows the mix and match of different application versions with different API versions and service-provider versions.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONE_BUTTON, PHONE_STATE, phoneNegotiateAPIVersion, phoneNegotiateExtVersion


phoneSetButtonInfo

The phoneSetButtonInfo function sets information about the specified button on the specified phone.

LONG phoneSetButtonInfo(
  HPHONE hPhone,
  DWORD dwButtonLampID,
  LPPHONEBUTTONINFO const lpButtonInfo
);

Parameters

hPhone
A handle to the open phone device. The application must be the owner of the phone device.
dwButtonLampID
A button on the phone device.
lpButtonInfo
A pointer to a variably sized structure of type PHONEBUTTONINFO. This data structure describes the mode, the function, and provides additional descriptive text about the button.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALBUTTONLAMPID, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONEHANDLE, PHONEERR_STRUCTURETOOSMALL, PHONEERR_INVALPOINTER, PHONEERR_UNINITIALIZED, PHONEERR_NOTOWNER, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_RESOURCEUNAVAIL.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONE_REPLY, PHONEBUTTONINFO


phoneSetData

The phoneSetData function downloads the information in the specified buffer to the opened phone device at the selected data identifier.

LONG phoneSetData(
  HPHONE hPhone,
  DWORD dwDataID,
  LPVOID const lpData,
  DWORD dwSize
);

Parameters

hPhone
A handle to the open phone device. The application must be the owner of the phone.
dwDataID
Where in the phone device the buffer is to be downloaded.
lpData
A pointer to the memory location where the data is to be downloaded from.
dwSize
The size of the buffer in bytes.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOTOWNER, PHONEERR_NOMEM, PHONEERR_INVALDATAID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPOINTER, PHONEERR_UNINITIALIZED.

Remarks

The phoneSetData function downloads a maximum of dwSize bytes from lpData to the phone device. The format of the data, its meaning to the phone device, and the meaning of the data identifier are service provider-specific. The data in the buffer or the selection of a data identifier may act as commands to the phone device.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONE_REPLY


phoneSetDisplay

The phoneSetDisplay function causes the specified string to be displayed on the specified open phone device.

LONG phoneSetDisplay(
  HPHONE hPhone,
  DWORD dwRow,
  DWORD dwColumn,
  LPCSTR lpsDisplay,
  DWORD dwSize
);

Parameters

hPhone
A handle to the open phone device. The application must be the owner of the phone.
dwRow
The row position on the display where the new text is to be displayed.
dwColumn
The column position on the display where the new text is to be displayed.
lpsDisplay
A pointer to the memory location where the display content is stored. The display information must have the format specified in the dwStringFormat member of the phone's device capabilities.
dwSize
The size in bytes of the information pointed to by lpsDisplay.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOTOWNER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_UNINITIALIZED, PHONEERR_INVALPOINTER, PHONEERR_NOMEM, PHONEERR_INVALPARAM, PHONEERR_RESOURCEUNAVAIL.

Remarks

The specified display information is written to the phone's display, starting at the specified positions. This operation overwrites previously displayed information. If the amount of information exceeds the size of the display, the information is truncated. The amount of information that can be displayed is at most (dwNumRows * dwNumColumns) elements in size. dwNumRows and dwNumColumns are available in the PHONECAPS structure, which is returned by phoneGetDevCaps; they are zero-based.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONE_REPLY, PHONECAPS, phoneGetDevCaps


phoneSetGain

The phoneSetGain function sets the gain of the microphone of the specified hookswitch device to the specified gain level.

LONG phoneSetGain(
  HPHONE hPhone,
  DWORD dwHookSwitchDev,
  DWORD dwGain
);

Parameters

hPhone
A handle to the open phone device. The application must be the owner of the phone.
dwHookSwitchDev
The hookswitch device whose microphone's gain is to be set. The dwHookswitchDev parameter can only have a single bit set. This parameter uses the following PHONEHOOKSWITCHDEV_ constants:
PHONEHOOKSWITCHDEV_HANDSET
The phone's handset.
PHONEHOOKSWITCHDEV_SPEAKER
The phone's speakerphone or adjunct.
PHONEHOOKSWITCHDEV_HEADSET
The phone's headset.
dwGain
A pointer to a DWORD-sized location containing the current gain setting of the device. The dwGain parameter specifies the gain level of the hookswitch device. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of gain settings in this range are service provider-specific. A value for dwGain that is out of range is set to the nearest value in the range.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_NOTOWNER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONE_REPLY


phoneSetHookSwitch

The phoneSetHookSwitch function sets the hook state of the specified open phone's hookswitch devices to the specified mode. Only the hookswitch state of the hookswitch devices listed is affected.

LONG phoneSetHookSwitch(
  HPHONE hPhone,
  DWORD dwHookSwitchDevs,
  DWORD dwHookSwitchMode
);

Parameters

hPhone
A handle to the open phone device. The application must be the owner of the phone.
dwHookSwitchDevs
The device or devices whose hookswitch mode is to be set. This parameter uses the following PHONEHOOKSWITCHDEV_ constants:
PHONEHOOKSWITCHDEV_HANDSET
The phone's handset.
PHONEHOOKSWITCHDEV_SPEAKER
The phone's speakerphone or adjunct.
PHONEHOOKSWITCHDEV_HEADSET
The phone's headset.
dwHookSwitchMode
The hookswitch mode to set. The dwHookSwitchMode parameter can have only a single bit set. This parameter uses the following PHONEHOOKSWITCHMODE_ constants:
PHONEHOOKSWITCHMODE_ONHOOK
The device's microphone and speaker are both onhook.
PHONEHOOKSWITCHMODE_MIC
The device's microphone is active, the speaker is mute.
PHONEHOOKSWITCHMODE_SPEAKER
The device's speaker is active, the microphone is mute.
PHONEHOOKSWITCHMODE_MICSPEAKER
The device's microphone and speaker are both active.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOTOWNER, PHONEERR_NOMEM, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALHOOKSWITCHMODE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_UNINITIALIZED.

Remarks

The hookswitch mode is the same for all specified devices. If different settings are desired, this function can be invoked multiple times with a different set of parameters. A PHONE_STATE message is sent to the application after the hookswitch state has changed.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONE_REPLY, PHONE_STATE


phoneSetLamp

The phoneSetLamp function causes the specified lamp to be lit on the specified open phone device in the specified lamp mode.

LONG phoneSetLamp(
  HPHONE hPhone,
  DWORD dwButtonLampID,
  DWORD dwLampMode
);

Parameters

hPhone
A handle to the open phone device. The application must be the owner of the phone.
dwButtonLampID
The button whose lamp is to be lit.
dwLampMode
How the lamp is to be lit. The dwLampMode parameter can have only a single bit set. This parameter uses the following PHONELAMPMODE_ constants:
PHONELAMPMODE_BROKENFLUTTER
Broken flutter is the superposition of flash and flutter.
PHONELAMPMODE_FLASH
Flash means slow on and off.
PHONELAMPMODE_FLUTTER
Flutter means fast on and off.
PHONELAMPMODE_OFF
The lamp is off.
PHONELAMPMODE_STEADY
The lamp is continuously lit.
PHONELAMPMODE_WINK
The lamp is winking.
PHONELAMPMODE_DUMMY
This value is used to describe a button/lamp position that has no corresponding lamp.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOTOWNER, PHONEERR_NOMEM, PHONEERR_INVALBUTTONLAMPID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALLAMPMODE, PHONEERR_UNINITIALIZED.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONE_REPLY


phoneSetRing

The phoneSetRing function rings the specified open phone device using the specified ring mode and volume.

LONG phoneSetRing(
  HPHONE hPhone,
  DWORD dwRingMode,
  DWORD dwVolume
);

Parameters

hPhone
A handle to the open phone device. The application must be the owner of the phone device.
dwRingMode
The ringing pattern with which to ring the phone. This parameter must be within the range of zero to the value of the dwNumRingModes member in the PHONECAPS structure. If dwNumRingModes is zero, the ring mode of the phone cannot be controlled; if dwNumRingModes is 1, a value of 0 for dwRingMode indicates that the phone should not be rung (silence), and other values from 1 to dwNumRingModes are valid ring modes for the phone device.
dwVolume
The volume level with which the phone is ringing. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service provider-specific. A value for dwVolume that is out of range is set to the nearest value in the range.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_NOTOWNER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALRINGMODE, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

Remarks

The service provider defines the actual audible ringing patterns corresponding to each of the phone's ring modes.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONE_REPLY, PHONECAPS


phoneSetStatusMessages

The phoneSetStatusMessages function enables an application to monitor the specified phone device for selected status events.

LONG phoneSetStatusMessages(
  HPHONE hPhone,
  DWORD dwPhoneStates,
  DWORD dwButtonModes,
  DWORD dwButtonStates
);

Parameters

hPhone
A handle to the open phone device to be monitored.
dwPhoneStates
These flags specify the set of phone status changes and events for which the application can receive notification messages. This parameter can have zero, one, or more bits set. This parameter uses the following PHONESTATE_ constants:
PHONESTATE_OTHER
Phone status items other than those listed below have changed. The application should check the current phone status to determine which items have changed.
PHONESTATE_CONNECTED
The connection between the phone device and TAPI was just made. This happens when TAPI is first invoked or when the wire connecting the phone to the PC is plugged in while TAPI is active.
PHONESTATE_DISCONNECTED
The connection between the phone device and TAPI was just broken. This happens when the wire connecting the phone set to the PC is unplugged while TAPI is active.
PHONESTATE_OWNER
The number of owners for the phone device has changed.
PHONESTATE_MONITORS
The number of monitors for the phone device has changed.
PHONESTATE_DISPLAY
The display of the phone has changed.
PHONESTATE_LAMP
A lamp of the phone has changed.
PHONESTATE_RINGMODE
The ring mode of the phone has changed.
PHONESTATE_RINGVOLUME
The ring volume of the phone has changed.
PHONESTATE_HANDSETHOOKSWITCH
The handset hookswitch state has changed.
PHONESTATE_HANDSETVOLUME
The handset's speaker volume setting has changed.
PHONESTATE_HANDSETGAIN
The handset's microphone gain setting has changed.
PHONESTATE_SPEAKERHOOKSWITCH
The speakerphone's hookswitch state has changed.
PHONESTATE_SPEAKERVOLUME
The speakerphone's speaker volume setting has changed.
PHONESTATE_SPEAKERGAIN
The speakerphone's microphone gain setting state has changed.
PHONESTATE_HEADSETHOOKSWITCH
The headset's hookswitch state has changed.
PHONESTATE_HEADSETVOLUME
The headset's speaker volume setting has changed.
PHONESTATE_HEADSETGAIN
The headset's microphone gain setting has changed.
PHONESTATE_SUSPEND
The application's use of the phone is temporarily suspended.
PHONESTATE_RESUME
The application's use of the phone device is resumed after having been suspended for some time.
PHONESTATE_DEVSPECIFIC
The phone's device-specific information has changed.
PHONESTATE_REINIT
Items have changed in the configuration of phone devices. To become aware of these changes (as with the appearance of new phone devices) the application should reinitialize its use of TAPI. New phoneInitialize, phoneInitializeEx and phoneOpen requests are denied until applications have shut down their usage of TAPI. The hDevice parameter of the PHONE_STATE message is left NULL for this state change, because it applies to any of the lines in the system. Because of the critical nature of PHONESTATE_REINIT, such messages cannot be masked, so the setting of this bit is ignored and the messages are always delivered to the application.
PHONESTATE_CAPSCHANGE
Indicates that due to configuration changes made by the user or other circumstances one or more of the members in the PHONECAPS structure have changed. The application should use phoneGetDevCaps to read the updated structure. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous TAPI version receive PHONE_STATE messages specifying PHONESTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI in order to obtain the updated information.
PHONESTATE_REMOVED
Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A PHONE_STATE message with this value is normally immediately followed by a PHONE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized result in PHONEERR_NODEVICE being returned to the application. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous TAPI version do not receive any notification.
dwButtonModes
The set of phone-button modes for which the application can receive notification messages. This parameter can have zero, one, or more bits set. This parameter uses the following PHONEBUTTONMODE_ constants:
PHONEBUTTONMODE_CALL
The button is assigned to a call appearance.
PHONEBUTTONMODE_FEATURE
The button is assigned to requesting features from the switch, such as hold, conference, and transfer.
PHONEBUTTONMODE_KEYPAD
The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'.
PHONEBUTTONMODE_LOCAL
The button is a local function button, such as mute or volume control.
PHONEBUTTONMODE_DISPLAY
The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.
dwButtonStates
The set of phone-button state changes for which the application can receive notification messages. If the dwButtonModes parameter is zero, dwButtonStates is ignored. If dwButtonModes has one or more bits set, this parameter must also have at least one bit set. This parameter uses the following PHONEBUTTONSTATE_ constants:
PHONEBUTTONSTATE_UP
The button is in the "up" state.
PHONEBUTTONSTATE_DOWN
The button is in the "down" state (pressed down).
PHONEBUTTONSTATE_UNKNOWN
Indicates that the up or down state of the button is not known at this time, but may become known at a future time.
PHONEBUTTONSTATE_UNAVAIL
Indicates that the up or down state of the button is not known to the service provider, and will not become known.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPHONESTATE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALBUTTONMODE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALBUTTONSTATE, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

Remarks

An application can use the phoneSetStatusMessages function to enable or disable the generation of the corresponding messages. All phone status messages are disabled by default.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONE_CLOSE, PHONE_STATE, PHONECAPS, phoneGetDevCaps, phoneInitialize, phoneInitializeEx, phoneOpen


phoneSetVolume

The phoneSetVolume function sets the volume of the speaker component of the specified hookswitch device to the specified level.

LONG phoneSetVolume(
  HPHONE hPhone,
  DWORD dwHookSwitchDev,
  DWORD dwVolume
);

Parameters

hPhone
A handle to the open phone device. The application must be the owner of the phone.
dwHookSwitchDev
The hookswitch device whose speaker's volume is to be set.
PHONEHOOKSWITCHDEV_HANDSET
The phone's handset.
PHONEHOOKSWITCHDEV_SPEAKER
The phone's speakerphone or adjunct.
PHONEHOOKSWITCHDEV_HEADSET
The phone's headset.
dwVolume
The current volume setting of the device. The dwVolume parameter specifies the volume level of the hookswitch device. This is a number in the range 0x00000000 (silence) to 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service provider-specific. A value for dwVolume that is out of range is set to the nearest value in the range.

Return Values

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_NOTOWNER, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_UNINITIALIZED, PHONEERR_OPERATIONUNAVAIL.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions, PHONE_REPLY


phoneShutdown

The phoneShutdown function shuts down the application's usage of TAPI's phone abstraction.

LONG phoneShutdown(
  HPHONEAPP hPhoneApp
);

Parameters

hPhoneApp
The application's usage handle for TAPI.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

PHONEERR_INVALAPPHANDLE, PHONEERR_NOMEM, PHONEERR_UNINITIALIZED, PHONEERR_RESOURCEUNAVAIL.

Remarks

If this function is called when the application has open phone devices, these devices are closed.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.


Assisted Telephony Functions

This section contains an alphabetic listing of the TAPI functions for Assisted Telephony services.

For a categorization of TAPI functions by service level and task, see TAPI Quick Function Reference.

See Also

TAPI Reference Overview, Supplementary Phone Services Functions


tapiGetLocationInfo

The tapiGetLocationInfo function returns the country code and city (area) code that the user has set in the current location parameters in the Telephony Control Panel. The application can use this information to assist the user in forming proper canonical telephone numbers, such as by offering these as defaults when new numbers are entered in a phone book entry or database record.

LONG tapiGetLocationInfo(
  LPCSTR lpszCountryCode,
  LPCSTR lpszCityCode
);

Parameters

lpszCountryCode
A pointer to a memory location where a NULL-terminated ASCII string specifying the country code for the current location is to be returned. The application should allocate at least 8 bytes of storage at this location to hold the string (TAPI does not return more than 8 bytes, including the terminating NULL). An empty string (\0) is returned if the country code has not been set for the current location.
lpszCityCode
A pointer to a memory location where a NULL-terminated ASCII string specifying the city (area) code for the current location is to be returned. The application should allocate at least 8 bytes of storage at this location to hold the string (TAPI does not return more than 8 bytes, including the terminating NULL). An empty string (\0) is returned if the city code has not been set for the current location.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are TAPIERR_REQUESTFAILED.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Assisted Telephony Services Reference


tapiRequestDrop

The tapiRequestDrop function is nonfunctional in Win32 -based applications and obsolete for all classes of Windows-based applications. It should not be used.

See Also

TAPI Reference Overview, Assisted Telephony Services Reference


tapiRequestMakeCall

The tapiRequestMakeCall function requests the establishment of a voice call. A call-manager application is responsible for establishing the call on behalf of the requesting application, which is then controlled by the user's call-manager application.

LONG tapiRequestMakeCall(
  LPCSTR lpszDestAddress,
  LPCSTR lpszAppName,
  LPCSTR lpszCalledParty,
  LPCSTR lpszComment
);

Parameters

lpszDestAddress
A pointer to a memory location where the NULL-terminated destination address of the call request is located. The address can use the canonical address format (address formats are discussed in Line Devices Overview) or the dialable address format. Validity of the specified address is not checked by this operation. The maximum length of the address is TAPIMAXDESTADDRESSSIZE characters, which includes the NULL terminator.
lpszAppName
A pointer to a memory location where the ASCII NULL-terminated user-friendly application name of the call request is located. This pointer can be left NULL if the application does not supply an application name. The maximum length of the address is TAPIMAXAPPNAMESIZE characters, which includes the NULL terminator. Longer strings are truncated.
lpszCalledParty
A pointer to a memory location where the ASCII NULL-terminated called party name for the called party of the call is located. This pointer can be left NULL if the application does not wish to supply this information. The maximum length of the string is TAPIMAXCALLEDPARTYSIZE characters, which includes the NULL terminator. Longer strings are truncated.
lpszComment
A pointer to a memory location where the ASCII NULL-terminated comment about the call is located. This pointer can be left NULL if the application does not supply a comment. The maximum length of the address is TAPIMAXCOMMENTSIZE characters, which includes the NULL terminator. Longer strings are truncated.

Return Values

Returns zero if the request succeeds or a negative error number if an error occurs. Possible error return value are:

TAPIERR_NOREQUESTRECIPIENT, TAPIERR_INVALDESTADDRESS, TAPIERR_REQUESTQUEUEFULL, TAPIERR_INVALPOINTER.

Remarks

A telephony-enabled application can request that a call be placed on its behalf by invoking tapiRequestMakeCall, providing only the destination address for the call. This request is forwarded to the user's call-control application, which places the call on behalf of the original application. A default call-control application is provided as part of Win32 Telephony. Users can replace this with a call-control application of their choice.

Invoking tapiRequestMakeCall when no call control application is running returns the TAPIERR_NOREQUESTRECIPIENT error indication. If the call control application is not running, TAPI attempts to launch the highest-priority call control application (which is listed for RequestMakeCall in the registry). Invoking this function when the Assisted TAPI request queue is full returns the TAPIERR_REQUESTQUEUEFULL error.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.

See Also

TAPI Reference Overview, Assisted Telephony Services Reference


tapiRequestMediaCall

The tapiRequestMediaCall function is nonfunctional in Win32-based applications and obsolete for all classes of Windows-based applications. It should not be used.

See Also

TAPI Reference Overview, Assisted Telephony Services Reference


TAPI Structures

This section contains the reference for the following Telephony Application Programming Interface (TAPI) structures:

Line Device Structures

Phone Device Structures


Line Device Structures

This section contains an alphabetic listing of the line device structures used by TAPI.


LINEADDRESSCAPS

The LINEADDRESSCAPS structure describes the capabilities of a specified address.

typedef struct lineaddresscaps_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwLineDeviceID;

    DWORD  dwAddressSize;
    DWORD  dwAddressOffset;

    DWORD  dwDevSpecificSize;
    DWORD  dwDevSpecificOffset;

    DWORD  dwAddressSharing;
    DWORD  dwAddressStates;
    DWORD  dwCallInfoStates;
    DWORD  dwCallerIDFlags;
    DWORD  dwCalledIDFlags;
    DWORD  dwConnectedIDFlags;
    DWORD  dwRedirectionIDFlags;
    DWORD  dwRedirectingIDFlags;
    DWORD  dwCallStates;
    DWORD  dwDialToneModes;
    DWORD  dwBusyModes;
    DWORD  dwSpecialInfo;
    DWORD  dwDisconnectModes;

    DWORD  dwMaxNumActiveCalls;
    DWORD  dwMaxNumOnHoldCalls;
    DWORD  dwMaxNumOnHoldPendingCalls;
    DWORD  dwMaxNumConference;
    DWORD  dwMaxNumTransConf;

    DWORD  dwAddrCapFlags;
    DWORD  dwCallFeatures;
    DWORD  dwRemoveFromConfCaps;
    DWORD  dwRemoveFromConfState;
    DWORD  dwTransferModes;
    DWORD  dwParkModes;

    DWORD  dwForwardModes;
    DWORD  dwMaxForwardEntries;
    DWORD  dwMaxSpecificEntries;
    DWORD  dwMinFwdNumRings;
    DWORD  dwMaxFwdNumRings;

    DWORD  dwMaxCallCompletions;
    DWORD  dwCallCompletionConds;
    DWORD  dwCallCompletionModes;
    DWORD  dwNumCompletionMessages;
    DWORD  dwCompletionMsgTextEntrySize;
    DWORD  dwCompletionMsgTextSize;
    DWORD  dwCompletionMsgTextOffset;
    DWORD  dwAddressFeatures;

    DWORD  dwPredictiveAutoTransferStates;
    DWORD  dwNumCallTreatments;
    DWORD  dwCallTreatmentListSize;
    DWORD  dwCallTreatmentListOffset;
    DWORD  dwDeviceClassesSize;
    DWORD  dwDeviceClassesOffset;
    DWORD  dwMaxCallDataSize;
    DWORD  dwCallFeatures2;
    DWORD  dwMaxNoAnswerTimeout;
    DWORD  dwConnectedModes;
    DWORD  dwOfferingModes;
    DWORD  dwAvailableMediaModes;
} LINEADDRESSCAPS, FAR *LPLINEADDRESSCAPS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwLineDeviceID
The device identifier of the line device with which this address is associated.
dwAddressSize
dwAddressOffset
The size in bytes of the variably sized address field and the offset in bytes from the beginning of this data structure.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes of the variably sized device-specific field and the offset in bytes from the beginning of this data structure.
dwAddressSharing
The sharing mode of the address. This member can be one of the following values:
LINEADDRESSSHARING_PRIVATE
An address with private sharing mode is only assigned to a single line or station.
LINEADDRESSSHARING_BRIDGEDEXCL
An address with a bridged-exclusive sharing mode is assigned to one or more other lines or stations. The exclusive portion refers to the fact that only one of the bridged parties can be connected with a remote party at any given time.
LINEADDRESSSHARING_BRIDGEDNEW
An address with a bridged-new sharing mode is assigned to one or more other lines or stations. The new portion refers to the fact that activities by the different bridged parties result in the creation of new calls on the address.
LINEADDRESSSHARING_BRIDGEDSHARED
An address with a bridged-shared sharing mode is also assigned to one or more other lines or stations. The shared portion refers to the fact that if one of the bridged parties is connected with a remote party, the remaining bridged parties can share in the conversation (as in a conference) by activating that call appearance.
LINEADDRESSSHARING_MONITORED
An address with a monitored address mode simply monitors the status of that address. The status is either idle or in use. The message LINE_ADDRESSSTATE notifies the application about these changes.
dwAddressStates
Contains the address states changes for which the application may get notified in the LINE_ADDRESSSTATE message. This member uses the following LINEADDRESSSTATE_ constants:
LINEADDRESSSTATE_OTHER
Address status items other than those listed below have changed. The application should check the current address status to determine which items have changed.
LINEADDRESSSTATE_DEVSPECIFIC
The device-specific item of the address status has changed.
LINEADDRESSSTATE_INUSEZERO
The address has changed to idle (it is not in use by any station).
LINEADDRESSSTATE_INUSEONE
The address has changed from being idle or from being in use by many bridged stations to being in use by just one station.
LINEADDRESSSTATE_INUSEMANY
The monitored or bridged address has changed from being in use by one station to being used by more than one station.
LINEADDRESSSTATE_NUMCALLS
The number of calls on the address has changed. This is the result of events such as a new incoming call, an outgoing call on the address, or a call changing its hold status.
LINEADDRESSSTATE_FORWARD
The forwarding status of the address has changed, including the number of rings for determining a no-answer condition. The application should check the address status to retrieve details about the address's current forwarding status.
LINEADDRESSSTATE_TERMINALS
The terminal settings for the address have changed.
LINEADDRESSSTATE_CAPSCHANGE
Indicates that due to configuration changes made by the user or other circumstances, one or more of the members in the LINEADDRESSCAPS structure for the address have changed. The application should use lineGetAddressCaps to read the updated structure. If a service provider sends a LINE_ADDRESSSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous TAPI version receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI to obtain the updated information.
dwCallInfoStates
Describes the call information elements that are meaningful for all calls on this address. An application may get notified about changes in some of these states in LINE_CALLINFO messages. This member uses the following LINECALLINFOSTATE_ constants:
LINECALLINFOSTATE_OTHER
Call information items other than those listed below have changed. The application should check the current call information to determine which items have changed.
LINECALLINFOSTATE_DEVSPECIFIC
The device-specific field of the call information.
LINECALLINFOSTATE_BEARERMODE
The bearer-mode field of the call information record.
LINECALLINFOSTATE_RATE
The rate field of the call information record.
LINECALLINFOSTATE_MEDIAMODE
The media-mode field of the call information record.
LINECALLINFOSTATE_APPSPECIFIC
The application-specific field of the call information record.
LINECALLINFOSTATE_CALLID
The call ID field of the call information record.
LINECALLINFOSTATE_RELATEDCALLID
The related call ID field of the call information record.
LINECALLINFOSTATE_ORIGIN
The origin field of the call information record.
LINECALLINFOSTATE_REASON
The reason field of the call information record.
LINECALLINFOSTATE_COMPLETIONID
The completion ID field of the call information record.
LINECALLINFOSTATE_NUMOWNERINCR
The number of owner fields in the call information record was increased.
LINECALLINFOSTATE_NUMOWNERDECR
The number of owner fields in the call information record was decreased.
LINECALLINFOSTATE_NUMMONITORS
The number of monitors field in the call information record has changed.
LINECALLINFOSTATE_TRUNK
The trunk field of the call information record has changed.
LINECALLINFOSTATE_CALLERID
One of the callerID-related fields of the call information record has changed.
LINECALLINFOSTATE_CALLEDID
One of the calledID-related fields of the call information record has changed.
LINECALLINFOSTATE_CONNECTEDID
One of the connectedID-related fields of the call information record has changed.
LINECALLINFOSTATE_REDIRECTIONID
One of the redirectionID-related fields of the call information record has changed.
LINECALLINFOSTATE_REDIRECTINGID
One of the redirectingID-related fields of the call information record has changed.
LINECALLINFOSTATE_DISPLAY
The display field of the call information record.
LINECALLINFOSTATE_USERUSERINFO
The user-user information field of the call information record.
LINECALLINFOSTATE_HIGHLEVELCOMP
The high-level compatibility field of the call information record.
LINECALLINFOSTATE_LOWLEVELCOMP
The low-level compatibility field of the call information record.
LINECALLINFOSTATE_CHARGINGINFO
The charging information field of the call information record.
LINECALLINFOSTATE_TERMINAL
The terminal mode information of the call information record.
LINECALLINFOSTATE_DIALPARAMS
The dial parameters of the call information record.
LINECALLINFOSTATE_MONITORMODES
One or more of the digit, tone, or media monitoring fields in the call information record has changed.
dwCallerIDFlags
dwCalledIDFlags
dwConnectedIDFlags
dwRedirectionIDFlags
dwRedirectingIDFlags
Describes the various party identifier information types that can be provided for calls on this address. This member uses the following LINECALLPARTYID_ constants:
LINECALLPARTYID_BLOCKED
Caller ID information for the call has been blocked by the caller but would otherwise have been available.
LINECALLPARTYID_OUTOFAREA
Caller ID information for the call is not available because it is not propagated all the way by the network.
LINECALLPARTYID_NAME
The caller ID information for the call is the caller's name (from a table maintained inside the switch). It is provided in the caller ID name variably sized field.
LINECALLPARTYID_ADDRESS
The caller ID information for the call is the caller's number and is provided in the caller ID variably sized field.
LINECALLPARTYID_PARTIAL
Caller ID information for the call is valid but is limited to partial number information.
LINECALLPARTYID_UNKNOWN
Caller ID information is currently unknown; it may become known later.
LINECALLPARTYID_UNAVAIL
Caller ID information is unavailable and cannot become known later.
dwCallStates
Describes the various call states that can possibly be reported for calls on this address. This member uses the following LINECALLSTATE_ constants:
LINECALLSTATE_IDLE
The call is idle—no call exists.
LINECALLSTATE_OFFERING
The call is being offered to the station, signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user; alerting is done by the switch instructing the line to ring. It does not affect any call states.
LINECALLSTATE_ACCEPTED
The call was offering and has been accepted. This indicates to other (monitoring) applications that the current owner application has claimed responsibility for answering the call. In ISDN, this also initiates alerting to both parties.
LINECALLSTATE_DIALTONE
The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number.
LINECALLSTATE_DIALING
Destination address information (a phone number) is being sent to the switch on the call. Note that the function lineGenerateDigits does not place the line into the dialing state.
LINECALLSTATE_RINGBACK
The call is receiving ringback from the called address. Ringback indicates that the other station has been reached and is being alerted.
LINECALLSTATE_BUSY
The call is receiving a busy tone. Busy tone indicates that the call cannot be completed—either a circuit (trunk) or the remote party's station are in use.
LINECALLSTATE_SPECIALINFO
Special information is sent by the network. Special information is typically sent when the destination cannot be reached.
LINECALLSTATE_CONNECTED
The call has been established and the connection is made. Information is able to flow on the call between the originating address and the destination address.
LINECALLSTATE_PROCEEDING
Dialing has completed and the call is proceeding through the switch or telephone network.
LINECALLSTATE_ONHOLD
The call is on hold by the switch.
LINECALLSTATE_CONFERENCED
The call is currently a member of a multiparty conference call.
LINECALLSTATE_ONHOLDPENDCONF
The call is currently on hold while it is being added to a conference call.
LINECALLSTATE_ONHOLDPENDTRANSF
The call is currently on hold awaiting transfer to another number.
LINECALLSTATE_DISCONNECTED
The remote party has disconnected from the call.
LINECALLSTATE_UNKNOWN
The state of the call is not known. This can be due to limitations of the call progress detection implementation.
dwDialToneModes
Describes the various dial tone modes that can possibly be reported for calls made on this address. This member is meaningful only if the dialtone call state can be reported. This member uses the following LINEDIALTONEMODE_ constants:
LINEDIALTONEMODE_NORMAL
A "normal" dial tone, which typically is a continuous tone.
LINEDIALTONEMODE_SPECIAL
A special dial tone indicating a certain condition is currently in effect.
LINEDIALTONEMODE_INTERNAL
An internal dial tone, as within a private branch exchange (PBX).
LINEDIALTONEMODE_EXTERNAL
An external (public network) dial tone.
LINEDIALTONEMODE_UNKNOWN
The dial tone mode is currently unknown but may become known later.
LINEDIALTONEMODE_UNAVAIL
The dial tone mode is unavailable and cannot become known.
dwBusyModes
Describes the various busy modes that can possibly be reported for calls made on this address. This member is meaningful only if the busy call state can be reported. This member uses the following LINEBUSYMODE_ constants:
LINEBUSYMODE_STATION
The busy signal indicates that the called party's station is busy. This is usually signaled with a "normal" busy tone.
LINEBUSYMODE_TRUNK
The busy signal indicates that a trunk or circuit is busy. This is usually signaled with a "long" busy tone.
LINEBUSYMODE_UNKNOWN
The busy signal's specific mode is currently unknown but may become known later.
LINEBUSYMODE_UNAVAIL
The busy signal's specific mode is unavailable and cannot become known.
dwSpecialInfo
Describes the various special information types that can possibly be reported for calls made on this address. This member is meaningful only if the specialInfo call state can be reported. This member uses the following LINESPECIALINFO_ constants:
LINESPECIALINFO_NOCIRCUIT
Special information tone that precedes a no-circuit or emergency announcement (trunk blockage category).
LINESPECIALINFO_CUSTIRREG
Special information tone that precedes a vacant number, Alarm Indication Signal (AIS), Centrex number change and nonworking station, access code not dialed or dialed in error, manual intercept operator message (customer irregularity category).
LINESPECIALINFO_REORDER
Special information tone that precedes a reorder announcement (equipment irregularity category).
LINESPECIALINFO_UNKNOWN
Specifics about the special information tone are currently unknown but may become known later.
LINESPECIALINFO_UNAVAIL
Specifics about the special information tone are unavailable and cannot become known.
dwDisconnectModes
Describes the various disconnect modes that can possibly be reported for calls made on this address. This member is meaningful only if the disconnected call state can be reported. This member uses the following LINEDISCONNECTMODE_ constants:
LINEDISCONNECTMODE_NORMAL
A "normal" disconnect request by the remote party; the call was terminated normally.
LINEDISCONNECTMODE_UNKNOWN
The reason for the disconnect request is unknown.
LINEDISCONNECTMODE_REJECT
The remote user has rejected the call.
LINEDISCONNECTMODE_PICKUP
The call was picked up from elsewhere.
LINEDISCONNECTMODE_FORWARDED
The call was forwarded by the switch.
LINEDISCONNECTMODE_BUSY
The remote user's station is busy.
LINEDISCONNECTMODE_NOANSWER
The remote user's station does not answer.
LINEDISCONNECTMODE_NODIALTONE
A dial tone was not detected within a service provider-defined timeout, at a point during dialing when one was expected (such as at a "W" in the dialable string). This can also occur without a service-provider-defined timeout period or without a value specified in the dwWaitForDialTone member of the LINEDIALPARAMS structure.
LINEDISCONNECTMODE_BADADDRESS
The destination address in invalid.
LINEDISCONNECTMODE_UNREACHABLE
The remote user could not be reached.
LINEDISCONNECTMODE_CONGESTION
The network is congested.
LINEDISCONNECTMODE_INCOMPATIBLE
The remote user's station equipment is incompatible with the type of call requested.
LINEDISCONNECTMODE_UNAVAIL
The reason for the disconnect is unavailable and cannot become known later.
dwMaxNumActiveCalls
Contains the maximum number of active call appearances that the address can handle. This number does not include calls on hold or calls on hold pending transfer or conference.
dwMaxNumOnHoldCalls
Contains the maximum number of call appearances at the address that can be on hold.
dwMaxNumOnHoldPendingCalls
Contains the maximum number of call appearances at the address that can be on hold pending transfer or conference.
dwMaxNumConference
Contains the maximum number of parties that can join a single conference call on this address.
dwMaxNumTransConf
Specifies the number of parties (including "self") that can be added in a conference call that is initiated as a generic consultation call using lineSetupTransfer.
dwAddrCapFlags
Contains a series of packed bit flags that describe a variety of address capabilities. This member uses the following LINEADDRCAPFLAGS_ constants:
LINEADDRCAPFLAGS_FWDNUMRINGS
Specifies whether the number of rings for a "no answer" can be specified when forwarding calls on no answer.
LINEADDRCAPFLAGS_PICKUPGROUPID
Specifies whether or not a group identifier is required for call pickup.
LINEADDRCAPFLAGS_SECURE
Specifies whether or not calls on this address can be made secure at call-setup time.
LINEADDRCAPFLAGS_BLOCKIDDEFAULT
Specifies whether the network by default sends or blocks caller ID information when making a call on this address. If TRUE, identifier information is blocked by default; if FALSE, identifier information is transmitted by default.
LINEADDRCAPFLAGS_BLOCKIDOVERRIDE
Specifies whether the default setting for sending or blocking of caller ID information can be overridden per call. If TRUE, override is possible; if FALSE, override is not possible.
LINEADDRCAPFLAGS_DIALED
Specifies whether a destination address can be dialed on this address for making a call. TRUE if a destination address must be dialed; FALSE if the destination address is fixed (as with a "hot phone").
LINEADDRCAPFLAGS_ORIGOFFHOOK
Specifies whether the originating party's phone can automatically be taken offhook when making calls.
LINEADDRCAPFLAGS_DESTOFFHOOK
Specifies whether the called party's phone can automatically be forced offhook when making calls.
LINEADDRCAPFLAGS_FWDCONSULT
Specifies whether call forwarding involves the establishment of a consultation call.
LINEADDRCAPFLAGS_SETUPCONFNULL
Specifies whether setting up a conference call starts out with an initial call (FALSE) or with no initial call (TRUE).
LINEADDRCAPFLAGS_AUTORECONNECT
Specifies whether dropping a consultation call automatically reconnects to the call on consultation hold. If reconnect happens automatically, TRUE; otherwise, FALSE.
LINEADDRCAPFLAGS_COMPLETIONID
Specifies whether the completion identifiers returned by lineCompleteCall are useful and unique. If useful, TRUE; otherwise, FALSE.
LINEADDRCAPFLAGS_TRANSFERHELD
Specifies whether a (hard) held call can be transferred. Often, only calls on consultation hold may be able to be transferred.
LINEADDRCAPFLAGS_CONFERENCEHELD
Specifies whether a (hard) held call can be added to a conference call. Often, only calls on consultation hold may be able to be added to a conference call.
LINEADDRCAPFLAGS_ PARTIALDIAL
Specifies whether partial dialing is available.
LINEADDRCAPFLAGS_FWDSTATUSVALID
Specifies whether the forwarding status in the LINEADDRESSSTATUS structure for this address is valid.
LINEADDRCAPFLAGS_ FWDINTEXTADDR
Specifies whether internal and external calls can be forwarded to different forwarding addresses. This flag is meaningful only if forwarding of internal and external calls can be controlled separately. It is TRUE if internal and external calls can be forwarded to different destination addresses; otherwise, FALSE.
LINEADDRCAPFLAGS_ FWDBUSYNAADDR
Specifies whether call forwarding for busy and for no answer can use different forwarding addresses. This flag is meaningful only if forwarding for busy and for no answer can be controlled separately. It is TRUE if forwarding for busy and for no answer can use different destination addresses; otherwise, FALSE.
LINEADDRCAPFLAGS_ACCEPTTOALERT
TRUE if an offering call must be accepted using lineAccept to start alerting the users at both ends of the call; otherwise, FALSE. Typically, this is only used with Integrated Services Digital Network (ISDN).
LINEADDRCAPFLAGS_CONFDROP
TRUE if invoking lineDrop on a conference call parent; TRUE also has the side effect of dropping the other parties involved in the conference call. FALSE if dropping a conference call; FALSE still allows the other parties to talk among themselves.
LINEADDRCAPFLAGS_ PICKUPCALLWAIT
TRUE if linePickup can be used to pick up a call detected by the user as a "call waiting" call; otherwise FALSE.
dwCallFeatures
Specifies the switching capabilities or features available for all calls on this address using the LINECALLFEATURE_ constants. This member represents the call-related features that may possibly be available on an address (static availability as opposed to dynamic availability). Invoking a supported feature requires the call to be in the proper state and the underlying line device to be opened in a compatible mode. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature may be available if the application has the right privileges to the call and the call is in the appropriate state for the operation to be meaningful. This member allows an application to discover which call features can be (and which can never be) supported by the address.
dwRemoveFromConfCaps
Specifies the address's capabilities for removing calls from a conference call. This member uses the following LINEREMOVEFROMCONF_ constants:
LINEREMOVEFROMCONF_NONE
Parties cannot be removed from the conference call.
LINEREMOVEFROMCONF_LAST
Only the most recently added party can be removed from the conference call.
LINEREMOVEFROMCONF_ANY
Any participating party can be removed from the conference call.
dwRemoveFromConfState
Uses the LINECALLSTATE_ constants to specify the state of the call after it has been removed from a conference call.
dwTransferModes
Specifies the address's capabilities for resolving transfer requests. This member uses the following LINETRANSFERMODE_ constants:
LINETRANSFERMODE_TRANSFER
Resolve the initiated transfer by transferring the initial call to the consultation call.
LINETRANSFERMODE_CONFERENCE
Resolve the initiated transfer by placing all three parties into a three-way conference call. A conference call is created and returned to the application.
dwParkModes
Specifies the different call park modes available at this address. This member uses the LINEPARKMODE_ constants:
LINEPARKMODE_DIRECTED
Specifies directed call park. The address where the call is to be parked must be supplied to the switch.
LINEPARKMODE_NONDIRECTED
Specifies nondirected call park. The address where the call is parked is selected by the switch and provided by the switch to the application.
dwForwardModes
Specifies the different modes of forwarding available for this address. This member uses the following LINEFORWARDMODE_ constants:
LINEFORWARDMODE_UNCOND
Forward all calls unconditionally, irrespective of their origin. Use this value when unconditional forwarding for internal and external calls cannot be controlled separately. Unconditional forwarding overrides forwarding on busy and/or no answer conditions.
LINEFORWARDMODE_UNCONDINTERNAL
Forward all internal calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.
LINEFORWARDMODE_UNCONDEXTERNAL
Forward all external calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.
LINEFORWARDMODE_UNCONDSPECIFIC
Forward all calls that originated at a specified address unconditionally (selective call forwarding).
LINEFORWARDMODE_BUSY
Forward all calls on busy, irrespective of their origin. Use this value when forwarding for internal and external calls on busy and on no answer cannot be controlled separately.
LINEFORWARDMODE_BUSYINTERNAL
Forward all internal calls on busy. Use this value when forwarding for internal and external calls on busy and on no answer can be controlled separately.
LINEFORWARDMODE_BUSYEXTERNAL
Forward all external calls on busy. Use this value when forwarding for internal and external calls on busy and on no answer can be controlled separately.
LINEFORWARDMODE_BUSYSPECIFIC
Forward all calls that originated at a specified address on busy (selective call forwarding).
LINEFORWARDMODE_NOANSW
Forward all calls on no answer, irrespective of their origin. Use this value when call forwarding for internal and external calls on no answer cannot be controlled separately.
LINEFORWARDMODE_NOANSWINTERNAL
Forward all internal calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.
LINEFORWARDMODE_NOANSWEXTERNAL
Forward all external calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.
LINEFORWARDMODE_NOANSWSPECIFIC
Forward all calls that originated at a specified address on no answer (selective call forwarding).
LINEFORWARDMODE_BUSYNA
Forward all calls on busy or no answer, irrespective of their origin. Use this value when forwarding; internal and external calls on busy and on no answer cannot be controlled separately.
LINEFORWARDMODE_BUSYNAINTERNAL
Forward all internal calls on busy or no answer. Use this value when call forwarding on busy and on no answer cannot be controlled separately for internal calls.
LINEFORWARDMODE_BUSYNAEXTERNAL
Forward all external calls on busy or no answer. Use this value when call forwarding on busy and on no answer cannot be controlled separately for internal calls.
LINEFORWARDMODE_BUSYNASPECIFIC
Forward all calls that originated at a specified address on busy or no answer (selective call forwarding).
dwMaxForwardEntries
Specifies the maximum number of entries that can be passed to lineForward in the lpForwardList parameter.
dwMaxSpecificEntries
Specifies the maximum number of entries in the lpForwardList parameter passed to lineForward that can contain forwarding instructions based on a specific caller ID (selective call forwarding). This member is zero if selective call forwarding is not supported.
dwMinFwdNumRings
Specifies the minimum number of rings that can be set to determine when a call is officially considered "no answer."
dwMaxFwdNumRings
Specifies the maximum number of rings that can be set to determine when a call is officially considered "no answer." If this number of rings cannot be set, then dwMinFwdNumRings and dwMaxNumRings are equal.
dwMaxCallCompletions
Specifies the maximum number of concurrent call completion requests that can be outstanding on this line device. Zero implies that call completion is not available.
dwCallCompletionConds
Specifies the different call conditions under which call completion can be requested. This member uses the following LINECALLCOMPLCOND_ constants:
LINECALLCOMPLCOND_BUSY
Complete the call under the busy condition.
LINECALLCOMPLCOND_NOANSWER
Complete the call under the ringback no answer condition.
dwCallCompletionModes
Specifies the way in which the call can be completed. This member uses the following LINECALLCOMPLCOND_ constants:
LINECALLCOMPLMODE_CAMPON
Queue the call until the call can be completed.
LINECALLCOMPLMODE_CALLBACK
Request the called station to return the call when it returns to idle.
LINECALLCOMPLMODE_INTRUDE
Add the application to the existing call at the called station if busy (barge in).
LINECALLCOMPLMODE_MESSAGE
Leave a short predefined message for the called station (Leave Word Calling). A specific message can be identified.
dwNumCompletionMessages
Specifies the number of call completion messages that can be selected from when using the LINECALLCOMPLMODE_MESSAGE option. Individual messages are identified by values in the range zero through one less than dwNumCompletionMessages.
dwCompletionMsgTextEntrySize
Specifies the size in bytes of each of the call completion text descriptions pointed at by dwCompletionMsgTextSize and dwCompletionMsgTextOffset.
dwCompletionMsgTextSize
dwCompletionMsgTextOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing descriptive text about each of the call completion messages. Each message is dwCompletionMsgTextEntrySize bytes long. The string format of these textual descriptions is indicated by dwStringFormat in the line's device capabilities.
dwAddressFeatures
Specifies the features available for this address using the LINEADDRFEATURE_ constants. Invoking a supported feature requires the address to be in the proper state and the underlying line device to be opened in a compatible mode. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature may be available if the address is in the appropriate state for the operation to be meaningful. This member allows an application to discover which address features can be (and which can never be) supported by the address.
dwPredictiveAutoTransferStates
The call state or states upon which a call made by a predictive dialer can be set to automatically transfer the call to another address; one or more of the LINECALLSTATE_ constants. The value 0 indicates automatic transfer based on call state is unavailable.
dwNumCallTreatments
The number of entries in the array of LINECALLTREATMENTENTRY structures delimited by dwCallTreatmentListSize and dwCallTreatmentListOffset.
dwCallTreatmentListSize
dwCallTreatmentListOffset
The total size in bytes and offset from the beginning of LINEADDRESSCAPS of an array of LINECALLTREATMENTENTRY structures, indicating the call treatments supported on the address (that can be selected using lineSetCallTreatment). The value is dwNumCallTreatments times SIZEOF (LINECALLTREATMENTENTRY).
dwDeviceClassesSize
dwDeviceClassesOffset
Length in bytes and offset from the beginning of LINEADDRESSCAPS of a string consisting of the device class identifiers supported on this address for use with lineGetID, separated by NULLs; the last class indentifier is followed by two NULLs.
dwMaxCallDataSize
The maximum number of bytes that an application can set in LINECALLINFO using lineSetCallData.
dwCallFeatures2
Specifies additional switching capabilities or features available for all calls on this address using the LINECALLFEATURE2_ constants. It is an extension of the dwCallFeatures member.
dwMaxNoAnswerTimeout
The maximum value in seconds that can be set in the dwNoAnswerTimeout member in LINECALLPARAMS when making a call. A value of 0 indicates that automatic abandonment of unanswered calls is not supported by the service provider, or that the timeout value is not adjustable by applications.
dwConnectedModes
Specifies the LINECONNECTEDMODE_ values that can appear in the dwCallStateMode member of LINECALLSTATUS and in LINE_CALLSTATE messages for calls on this address.
dwOfferingModes
Specifies the LINEOFFERINGMODE_ values that can appear in the dwCallStateMode member of LINECALLSTATUS and in LINE_CALLSTATE messages for calls on this address.
dwAvailableMediaModes
Indicates the media modes that can be invoked on new calls created on this address, when the dwAddressFeatures member indicates that new calls are possible. If this member is zero, it indicates that the service provider either does not know or cannot indicate which media modes are available, in which case any or all of the media modes indicated in the dwMediaModes member in LINEDEVCAPS may be available.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

Older applications are compiled without this member in the LINEADDRESSCAPS structure, and using a SIZEOF LINEADDRESSCAPS smaller than the new size. The application passes in a dwAPIVersion parameter with the lineGetAddressCaps function, which can be used for guidance by TAPI in handling this situation. If the application passes in a dwTotalSize member less than the size of the fixed portion of the structure as defined in the dwAPIVersion member specified, LINEERR_STRUCTURETOOSMALL is returned. If sufficient memory has been allocated by the application, before calling TSPI_lineGetAddressCaps, TAPI sets the dwNeededSize and dwUsedSize members to the fixed size of the structure as it existed in the specified API version.

New service providers (that support the new API version) must examine the API version passed in. If the API version is less than the highest version supported by the provider, the service provider must not fill in fields not supported in older API versions, as these would fall in the variable portion of the older structure.

New applications must be cognizant of the API version negotiated, and not examine the contents of fields in the fixed portion beyond the original end of the fixed portion of the structure for the negotiated API version.

The members dwPredictiveAutoTransferStates through dwAvailableMediaModes are available only to applications that request an API version of 2.0 or later when calling lineGetAddressCaps.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINE_ADDRESSSTATE, LINE_CALLINFO, LINE_CALLSTATE, LINE_LINEDEVSTATE, LINEADDRESSSTATUS, LINECALLINFO, LINECALLPARAMS, LINECALLSTATUS, LINECALLTREATMENTENTRY, LINEDEVCAPS, LINEDIALPARAMS, lineCompleteCall, lineForward, lineGenerateDigits, lineGetAddressCaps, lineGetID, lineSetCallData, lineSetCallTreatment


LINEADDRESSSTATUS

The LINEADDRESSSTATUS structure describes the current status of an address.

typedef struct lineaddressstatus_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwNumInUse;
    DWORD  dwNumActiveCalls;
    DWORD  dwNumOnHoldCalls;
    DWORD  dwNumOnHoldPendCalls;
    DWORD  dwAddressFeatures;

    DWORD  dwNumRingsNoAnswer;
    DWORD  dwForwardNumEntries;
    DWORD  dwForwardSize;
    DWORD  dwForwardOffset;

    DWORD  dwTerminalModesSize;
    DWORD  dwTerminalModesOffset;

    DWORD  dwDevSpecificSize;
    DWORD  dwDevSpecificOffset;
} LINEADDRESSSTATUS, FAR *LPLINEADDRESSSTATUS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwNumInUse
Specifies the number of stations that are currently using the address.
dwNumActiveCalls
The number of calls on the address that are in call states other than idle, onhold, onholdpendingtransfer, and onholdpendingconference.
dwNumOnHoldCalls
The number of calls on the address in the onhold state.
dwNumOnHoldPendCalls
The number of calls on the address in the onholdpendingtransfer or onholdpendingconference state.
dwAddressFeatures
Specifies the address-related API functions that can be invoked on the address in its current state. This member uses the following LINEADDRFEATURE_ constants:
LINEADDRFEATURE_FORWARD
The address can be forwarded.
LINEADDRFEATURE_MAKECALL
An outgoing call can be placed on the address.
LINEADDRFEATURE_PICKUP
A call can be picked up at the address.
LINEADDRFEATURE_SETMEDIACONTROL
Media control can be set on this address.
LINEADDRFEATURE_SETTERMINAL
The terminal modes for this address can be set.
LINEADDRFEATURE_SETUPCONF
A conference call with a NULL initial call can be set up at this address.
LINEADDRFEATURE_UNCOMPLETECALL
Call completion requests can be canceled at this address.
LINEADDRFEATURE_UNPARK
Calls can be unparked using this address.
dwNumRingsNoAnswer
The number of rings set for this address before an unanswered call is considered as no answer.
dwForwardNumEntries
The number of entries in the array referred to by dwForwardSize and dwForwardOffset.
dwForwardSize
dwForwardOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field that describes the address's forwarding information. This information is an array of dwForwardNumEntries elements, of type LINEFORWARD. The offsets of the addresses in the array are relative to the beginning of the LINEADDRESSSTATUS structure. The offsets dwCallerAddressOffset and dwDestAddressOffset in the variably sized field of type LINEFORWARD pointed to by dwForwardSize and dwForwardOffset are relative to the beginning of the LINEADDRESSSTATUS data structure (the "root" container).
dwTerminalModesSize
dwTerminalModesOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device field containing an array with DWORD-sized entries, that use the LINETERMMODE_ constants. This array is indexed by terminal identifiers, in the range from zero to one less than dwNumTerminals. Each entry in the array specifies the current terminal modes for the corresponding terminal set with the lineSetTerminal function for this address. Values are:
LINETERMMODE_LAMPS
Lamp events sent from the line to the terminal.
LINETERMMODE_BUTTONS
Button-press events sent from the terminal to the line.
LINETERMMODE_DISPLAY
Display information sent from the line to the terminal.
LINETERMMODE_RINGER
Ringer-control information sent from the switch to the terminal.
LINETERMMODE_HOOKSWITCH
Hookswitch events sent between the terminal and the line.
LINETERMMODE_MEDIATOLINE
The unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIAFROMLINE
The unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIABIDIRECT
The bidirectional media stream associated with a call on the line and the terminal. Use this value when the routing of both unidirectional channels of a call's media stream cannot be controlled independently.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device-specific field.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

This data structure is returned by the lineGetAddressStatus function. When items in this data structure change as a consequence of activities on the address, a LINE_ADDRESSSTATE message is sent to the application. A parameter to this message is the address state, the constant LINEADDRESSSTATE_, which is an indication that the status item in this record changed.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINE_ADDRESSSTATE, LINEFORWARD, lineGetAddressStatus, lineSetTerminal


LINEAGENTACTIVITYENTRY

typedef struct lineagentactivityentry_tag {
    DWORD  dwID;
    DWORD  dwNameSize;
    DWORD  dwNameOffset;
} LINEAGENTACTIVITYENTRY, FAR *LPLINEAGENTACTIVITYENTRY;

Members

dwID
A unique identifier for a activity. It is the responsibility of the agent handler to generate and maintain uniqueness of these identifiers.
dwNameSize
dwNameOffset
Size in bytes and offset from the beginning of the containing structure of a NULL-terminated string specifying the name and other identifying information of an activity that can be selected using lineSetAgentActivity.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.

See Also

LINEPROXYREQUEST, lineSetAgentActivity


LINEAGENTACTIVITYLIST

typedef struct lineagentactivitylist_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;
    DWORD  dwNumEntries;
    DWORD  dwListSize;
    DWORD  dwListOffset;
} LINEAGENTACTIVITYLIST, FAR *LPLINEAGENTACTIVITYLIST;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes needed to hold all the information requested.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwNumEntries
The number of LINEAGENTACTIVITYENTRY structures that appear in the List array. The value is 0 if no agent activity codes are available.
dwListSize
dwListOffset
Total size in bytes and offset from the beginning of LINEAGENTACTIVITYLIST of an array of LINEAGENTACTIVITYENTRY elements indicating information about activity that could be specified for the current logged-in agent. This is dwNumEntries times SIZEOF (LINEAGENTACTIVITYENTRY).

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.


LINEAGENTCAPS

typedef struct lineagentcaps_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwAgentHandlerInfoSize;
    DWORD  dwAgentHandlerInfoOffset;
    DWORD  dwCapsVersion;

    DWORD  dwFeatures;
    DWORD  dwStates;
    DWORD  dwNextStates;
    DWORD  dwMaxNumGroupEntries;
    DWORD  dwAgentStatusMessages;
    DWORD  dwNumAgentExtensionIDs;
    DWORD  dwAgentExtensionIDListSize;
    DWORD  dwAgentExtensionIDListOffset;
} LINEAGENTCAPS, FAR *LPLINEAGENTCAPS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes needed to hold all the information requested.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwAgentHandlerInfoSize
dwAgentHandlerInfoOffset
The size in bytes and offset from the beginning of LINEAGENTCAPS of a NULL-terminated string specifying the name, version, or other identifying information of the server application that is handling agent requests.
dwCapsVersion
The TAPI version that the agent handler application used in preparing the contents of this structure. This is no greater than the API version that the calling application passed in to lineGetAgentCaps.
dwFeatures
The agent-related features available for this line using the LINEAGENTFEATURE_ constants. Invoking a supported feature requires the line and address to be in the proper state. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature may be available if the line is in the appropriate state for the operation to be meaningful. This field allows an application to discover which agent features can be (and which can never be) supported by the device.
dwStates
The LINEAGENTSTATE_ values that can be used in the dwAgentState parameter of lineSetAgentState. Setting a supported state requires the line and address to be in the proper state. A zero in a bit position indicates that the corresponding state is never available. A one indicates that the corresponding state may be available if the line is in the appropriate state for the state to be meaningful. This field allows an application to discover which agent states can be (and which can never be) supported on the device.
dwNextStates
The LINEAGENTSTATE_ values that can be used in the dwNextAgentState parameter of lineSetAgentState. Setting a supported state requires the line and address to be in the proper state. A zero in a bit position indicates that the corresponding state is never available. A one indicates that the corresponding state may be available if the line is in the appropriate state for the state to be meaningful. This field allows an application to discover which agent states can be (and which can never be) supported on the device.
dwMaxNumGroupEntries
The maximum number of agent identifiers that can be logged in on the address simultaneously. Determines the highest value that can be passed in as the dwNumEntries member in the LINEAGENTGROUPLIST structure to lineSetAgentGroup.
dwAgentStatusMessages
Indicates the LINEAGENTSTATUS_ constants that can be received by the application in dwParam2 of a LINE_AGENTSTATUS message.
dwNumAgentExtensionIDs
The number of LINEEXTENSIONID structures that appear in the ExtensionIDList array. The value is 0 if agent-handler-specific extensions are supported on the address.
dwAgentExtensionIDListSize
dwAgentExtensionIDListOffset
Total size in bytes and offset from the beginning of LINEAGENTCAPS of an array of LINEEXTENSIONID elements. The size is dwNumExtensionIDs times SIZEOF (LINEEXTENSIONID). The array lists the 128-bit universally unique identifiers for all agent-handler-specific extensions supported by the agent handle for the address. The extension being used is referenced in the lineAgentSpecific function and LINE_AGENTSPECIFIC message by its position in this table, the first entry being entry 0, so it is important that the agent handler always present extension identifiers in this array in the same order.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.

See Also

LINE_AGENTSPECIFIC, LINE_AGENTSTATUS, LINEAGENTGROUPLIST, lineAgentSpecific, LINEEXTENSIONID, lineGetAgentCaps, LINEPROXYREQUEST, lineSetAgentGroup, lineSetAgentState


LINEAGENTGROUPENTRY

typedef struct lineagentgroupentry_tag {
  struct {
    DWORD  dwGroupID1;
    DWORD  dwGroupID2;
    DWORD  dwGroupID3;
    DWORD  dwGroupID4;
  } GroupID;
  DWORD  dwNameSize;
  DWORD  dwNameOffset;
} LINEAGENTGROUPENTRY, FAR *LPLINEAGENTGROUPENTRY;

Members

dwGroupID1
dwGroupID2
dwGroupID3
dwGroupID4
This set of four DWORDs is a universally unique identifier for a group. It is the responsibility of the agent handler to generate and maintain uniqueness of these identifiers.
dwNameSize
dwNameOffset
Size in bytes and offset from the beginning of the containing structure of a NULL-terminated string specifying the name and other identifying information of an ACD group or queue into which the agent can log in. This string can contain such information as supervisor and skill level, to assist the agent in selecting the correct group from a list displayed on their workstation screen.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.


LINEAGENTGROUPLIST

typedef struct lineagentgrouplist_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;
    DWORD  dwNumEntries;
    DWORD  dwListSize;
    DWORD  dwListOffset;
} LINEAGENTGROUPLIST, FAR *LPLINEAGENTGROUPLIST;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes needed to hold all the information requested.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwNumEntries
The number of LINEAGENTGROUPENTRY structures that appear in the List array. The value is 0 if no agent is to be logged in on the address.
dwListSize
dwListOffset
Total size in bytes and offset from the beginning of LINEAGENTGROUPLIST of an array of LINEAGENTGROUPENTRY elements specifying information about each group into which the current agent is to be logged in at the address. This is dwNumEntries times SIZEOF (LINEAGENTGROUPENTRY).

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.


LINEAGENTSTATUS

typedef struct lineagentstatus_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwNumEntries;
    DWORD  dwGroupListSize;
    DWORD  dwGroupListOffset;

    DWORD  dwState;
    DWORD  dwNextState;
    DWORD  dwActivityID;
    DWORD  dwActivitySize;
    DWORD  dwActivityOffset;

    DWORD  dwAgentFeatures;
    DWORD  dwValidStates;
    DWORD  dwValidNextStates;
} LINEAGENTSTATUS, FAR *LPLINEAGENTSTATUS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes needed to hold all the information requested.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwNumEntries
The number of LINEAGENTGROUPENTRY structures that appear in the GroupList array. The value is 0 if no agent is logged in on the address.
dwGroupListSize
dwGroupListOffset
Total size in bytes and offset from the beginning of LINEAGENTSTATUS of an array of LINEAGENTGROUPENTRY elements. The size is dwNumEntries times SIZEOF (LINEAGENTGROUPENTRY). The array contains groups into which the agent is currently logged in on the address.
dwState
The current state of the agent. One of the LINEAGENTSTATE_ constants.
dwNextState
The state into which the agent is automatically placed when the current call completes. One of the LINEAGENTSTATE_ constants.
dwActivityID
The identifier of the current agent activity.
dwActivitySize
dwActivityOffset
Size in bytes and offset from the beginning of LINEAGENTSTATUS of a NULL-terminated string specifying the current agent activity.
dwAgentFeatures
The agent-related features available at the time the status was obtained, using the LINEAGENTFEATURE_ constants.
dwValidStates
The agent states that could be selected, at this point in time, using lineSetAgentState. Consists of one or more of the LINEAGENTSTATE_ constants.
dwValidNextStates
The next agent states that could be selected, at this point in time, using lineSetAgentState. Consists of one or more of the LINEAGENTSTATE_ constants.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.

See Also

LINEAGENTGROUPENTRY, lineSetAgentState


LINEAPPINFO

typedef struct lineappinfo_tag {
} LINEAPPINFO, FAR *LPLINEAPPINFO;
    DWORD  dwMachineNameSize;
    DWORD  dwMachineNameOffset;
    DWORD  dwUserNameSize;
    DWORD  dwUserNameOffset;
    DWORD  dwModuleFilenameSize;
    DWORD  dwModuleFilenameOffset;
    DWORD  dwFriendlyNameSize;
    DWORD  dwFriendlyNameOffset;
    DWORD  dwMediaModes;
    DWORD  dwAddressID;

Members

dwMachineNameSize
dwMachineNameOffset
Size in bytes and offset from the beginning of LINEDEVSTATUS of a string specifying the name of the computer on which the application is executing.
dwUserNameSize
dwUserNameOffset
Size in bytes and offset from the beginning of LINEDEVSTATUS of a string specifying the user name under whose account the application is running.
dwModuleFilenameSize
dwModuleFilenameOffset
Size in bytes and offset from the beginning of LINEDEVSTATUS of a string specifying the module filename of the application. This string can be used in a call to lineHandoff to perform a directed handoff to the application.
dwFriendlyNameSize
dwFriendlyNameOffset
Size in bytes and offset from the beginning of LINEDEVSTATUS of the string provided by the application to lineInitialize or lineInitializeEx, which should be used in any display of applications to the user.
dwMediaModes
The media modes for which the application has requested ownership of new calls; zero if when it opened the line dwPrivileges did not include LINECALLPRIVILEGE_OWNER.
dwAddressID
If the line handle was opened using LINEOPENOPTION_SINGLEADDRESS, contains the address identifier specified; set to 0xFFFFFFFF if the single address option was not used.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.

See Also

LINEDEVSTATUS, lineHandoff, lineInitialize, lineInitializeEx


LINECALLINFO

The LINECALLINFO structure contains information about a call. This information remains relatively fixed for the duration of the call and is obtained with lineGetCallInfo. If a part of the structure does change, then a LINE_CALLINFO message is sent to the application indicating which information item has changed. Dynamically changing information about a call, such as call progress status, is available in the LINECALLSTATUS structure, returned with the lineGetCallStatus function.

typedef struct linecallinfo_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

  HLINE  hLine;
    DWORD  dwLineDeviceID;
    DWORD  dwAddressID;

    DWORD  dwBearerMode;
    DWORD  dwRate;
    DWORD  dwMediaMode;

    DWORD  dwAppSpecific;
    DWORD  dwCallID;
    DWORD  dwRelatedCallID;
    DWORD  dwCallParamFlags;
    DWORD  dwCallStates;

    DWORD  dwMonitorDigitModes;
    DWORD  dwMonitorMediaModes;
  LINEDIALPARAMS  DialParams;

    DWORD  dwOrigin;
    DWORD  dwReason;
    DWORD  dwCompletionID;
    DWORD  dwNumOwners;
    DWORD  dwNumMonitors;

    DWORD  dwCountryCode;
    DWORD  dwTrunk;

    DWORD  dwCallerIDFlags;
    DWORD  dwCallerIDSize;
    DWORD  dwCallerIDOffset;
    DWORD  dwCallerIDNameSize;
    DWORD  dwCallerIDNameOffset;

    DWORD  dwCalledIDFlags;
    DWORD  dwCalledIDSize;
    DWORD  dwCalledIDOffset;
    DWORD  dwCalledIDNameSize;
    DWORD  dwCalledIDNameOffset;

    DWORD  dwConnectedIDFlags;
    DWORD  dwConnectedIDSize;
    DWORD  dwConnectedIDOffset;
    DWORD  dwConnectedIDNameSize;
    DWORD  dwConnectedIDNameOffset;

    DWORD  dwRedirectionIDFlags;
    DWORD  dwRedirectionIDSize;
    DWORD  dwRedirectionIDOffset;
    DWORD  dwRedirectionIDNameSize;
    DWORD  dwRedirectionIDNameOffset;

    DWORD  dwRedirectingIDFlags;
    DWORD  dwRedirectingIDSize;
    DWORD  dwRedirectingIDOffset;
    DWORD  dwRedirectingIDNameSize;
    DWORD  dwRedirectingIDNameOffset;

    DWORD  dwAppNameSize;
    DWORD  dwAppNameOffset;
    DWORD  dwDisplayableAddressSize;
    DWORD  dwDisplayableAddressOffset;

    DWORD  dwCalledPartySize;
    DWORD  dwCalledPartyOffset;

    DWORD  dwCommentSize;
    DWORD  dwCommentOffset;

    DWORD  dwDisplaySize;
    DWORD  dwDisplayOffset;

    DWORD  dwUserUserInfoSize;
    DWORD  dwUserUserInfoOffset;

    DWORD  dwHighLevelCompSize;
    DWORD  dwHighLevelCompOffset;

    DWORD  dwLowLevelCompSize;
    DWORD  dwLowLevelCompOffset;

    DWORD  dwChargingInfoSize;
    DWORD  dwChargingInfoOffset;

    DWORD  dwTerminalModesSize;
    DWORD  dwTerminalModesOffset;

    DWORD  dwDevSpecificSize;
    DWORD  dwDevSpecificOffset;

    DWORD  dwCallTreatment;
    DWORD  dwCallDataSize;
    DWORD  dwCallDataOffset;
    DWORD  dwSendingFlowspecSize;
    DWORD  dwSendingFlowspecOffset;
    DWORD  dwReceivingFlowspecSize;
    DWORD  dwReceivingFlowspecOffset;

} LINECALLINFO, FAR *LPLINECALLINFO;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
hLine
The handle for the line device with which this call is associated.
dwLineDeviceID
The device identifier of the line device with which this call is associated.
dwAddressID
The address identifier of the address on the line on which this call exists.
dwBearerMode
The current bearer mode of the call. This member uses the following LINEBEARERMODE_ constants:
LINEBEARERMODE_VOICE
A regular 3.1 kHz analog voice grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.
LINEBEARERMODE_SPEECH
Corresponds to G.711 speech transmission on the call. The network can use processing techniques such as analog transmission, echo cancellation, and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.
LINEBEARERMODE_MULTIUSE
The multiuse mode defined by ISDN.
LINEBEARERMODE_DATA
The unrestricted data transfer on the call. The data rate is specified separately.
LINEBEARERMODE_ALTSPEECHDATA
The alternate transfer of speech or unrestricted data on the same call (ISDN).
LINEBEARERMODE_NONCALLSIGNALING
A non-call-associated signaling connection from the application to the service provider or switch (treated as a "media stream" by TAPI).
LINEBEARERMODE_PASSTHROUGH
When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 comm functions, for the purpose of configuring or using special features not otherwise supported by the service provider.
dwRate
The rate of the call's data stream in bps (bits per second).
dwMediaMode
Specifies the media mode of the information stream currently on the call. This is the media mode as determined by the owner of the call, which is not necessarily the same as that of the last LINE_MONITORMEDIA message. This member is not directly affected by the LINE_MONITORMEDIA messages. This member uses the following LINEMEDIAMODE_ constants:
LINEMEDIAMODE_UNKNOWN
A media stream exists but its mode is not known. This corresponds to a call with an unclassified media type. In typical analog telephony environments, an incoming call's media mode may be unknown until after the call has been answered and the media stream has been filtered to make a determination.
LINEMEDIAMODE_INTERACTIVEVOICE
The presence of voice energy is detected on the call and the call is treated as an interactive call with humans on both ends.
LINEMEDIAMODE_AUTOMATEDVOICE
The presence of voice energy is detected on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM
A datamodem session is detected on the call.
LINEMEDIAMODE_G3FAX
A group 3 fax is being sent or received on the call.
LINEMEDIAMODE_G4FAX
A group 4 fax is being sent or received on the call.
LINEMEDIAMODE_TDD
A TDD (Telephony Devices for the Deaf) session on the call.
LINEMEDIAMODE_DIGITALDATA
Digital data being sent or received on the call.
LINEMEDIAMODE_TELETEX
A teletex session on the call. Teletex is one of the telematic services.
LINEMEDIAMODE_VIDEOTEX
A videotex session on the call. Videotex is one of the telematic services.
LINEMEDIAMODE_TELEX
A telex session on the call. Telex is one of the telematic services.
LINEMEDIAMODE_MIXED
A mixed session on the call. Mixed is one of the ISDN telematic services.
LINEMEDIAMODE_ADSI
An ADSI (Analog Display Services Interface) session on the call.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.
dwAppSpecific
Uninterpreted by the API implementation and service provider. It can be set by any owner application of this call with the lineSetAppSpecific function.
dwCallID
In some telephony environments, the switch or service provider can assign a unique identifier to each call. This allows the call to be tracked across transfers, forwards, or other events. The domain of these call IDs and their scope is service provider-defined. The dwCallID member makes this unique identifier available to the applications.
dwRelatedCallID
Telephony environments that use the call ID often may find it necessary to relate one call to another. The dwRelatedCallID member may be used by the service provider for this purpose.
dwCallParamFlags
A collection of call-related parameters when the call is outgoing. These are the same call parameters specified in lineMakeCall, of type LINECALLPARAMFLAGS_. Values are:
LINECALLPARAMFLAGS_SECURE
The call is currently secure. This flag is also updated if the call is later secured through lineSecureCall.
LINECALLPARAMFLAGS_IDLE
The call started out using an idle call.
LINECALLPARAMFLAGS_BLOCKID
The originator identity was concealed (block caller ID presentation to the remote party).
LINECALLPARAMFLAGS_ORIGOFFHOOK
The originator's phone was automatically taken offhook.
LINECALLPARAMFLAGS_DESTOFFHOOK
The called party's phone was automatically taken offhook.
dwCallStates
The call states of type LINECALLSTATE_ for which the application can be notified on this call. The dwCallStates member is constant in LINECALLINFO and does not change depending on the call state. Values are:
LINECALLSTATE_IDLE
The call is idle—no call exists.
LINECALLSTATE_OFFERING
The call is being offered to the station signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user; alerting is done by the switch instructing the line to ring. It does not affect any call states.
LINECALLSTATE_ACCEPTED
The call was offering and has been accepted. This indicates to other (monitoring) applications that the current owner application has claimed responsibility for answering the call. In ISDN, this also initiates alerting to both parties.
LINECALLSTATE_DIALTONE
The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number.
LINECALLSTATE_DIALING
Destination address information (a phone number) is being sent to the switch on the call. The lineGenerateDigits function does not place the line into the dialing state.
LINECALLSTATE_RINGBACK
The call is receiving ringback from the called address. Ringback indicates that the other station has been reached and is being alerted.
LINECALLSTATE_BUSY
The call is receiving a busy tone. Busy tone indicates that the call cannot be completed—either a circuit (trunk) or the remote party's station are in use.
LINECALLSTATE_SPECIALINFO
Special information is sent by the network. Special information is typically sent when the destination cannot be reached.
LINECALLSTATE_CONNECTED
The call has been established, the connection is made. Information is able to flow on the call between the originating address and the destination address.
LINECALLSTATE_PROCEEDING
Dialing has completed and the call is proceeding through the switch or telephone network.
LINECALLSTATE_ONHOLD
The call is on hold by the switch.
LINECALLSTATE_CONFERENCED
The call is currently a member of a multiparty conference call.
LINECALLSTATE_ONHOLDPENDCONF
The call is currently on hold while it is being added to a conference.
LINECALLSTATE_ONHOLDPENDTRANSF
The call is currently on hold awaiting transfer to another number.
LINECALLSTATE_DISCONNECTED
The remote party has disconnected from the call.
LINECALLSTATE_UNKNOWN
The state of the call is not known. This may be due to limitations of the call progress detection implementation.
dwMonitorDigitModes
The various digit modes of type LINEDIGITMODE_ for which monitoring is currently enabled. Values are:
LINEDIGITMODE_PULSE
Uses pulse/rotary for digit signaling.
LINEDIGITMODE_DTMF
Uses DTMF tones for digit signaling.
LINEDIGITMODE_DTMFEND
Uses DTMF tones for digit detection, and also detects the down edges.
dwMonitorMediaModes
The various media modes for which monitoring is currently enabled, of type LINEMEDIAMODE_. Values are:
LINEMEDIAMODE_INTERACTIVEVOICE
The presence of voice energy on the call and the call is treated as an interactive call with humans on both ends.
LINEMEDIAMODE_AUTOMATEDVOICE
The presence of voice energy on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM
A datamodem session on the call.
LINEMEDIAMODE_G3FAX
A group 3 fax is being sent or received on the call.
LINEMEDIAMODE_G4FAX
A group 4 fax is being sent or received on the call.
LINEMEDIAMODE_TDD
A TDD (Telephony Devices for the Deaf) session on the call.
LINEMEDIAMODE_DIGITALDATA
Digital data is being sent or received on the call.
LINEMEDIAMODE_TELETEX
A teletex session on the call. Teletex is one of the telematic services.
LINEMEDIAMODE_VIDEOTEX
A videotex session on the call. Videotex is one of the telematic services.
LINEMEDIAMODE_TELEX
A telex session on the call. Telex is one of the telematic services.
LINEMEDIAMODE_MIXED
A mixed session on the call. Mixed is one of the ISDN telematic services.
LINEMEDIAMODE_ADSI
An ADSI (Analog Display Services Interface) session on the call.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.
DialParams
The dialing parameters currently in effect on the call, of type LINEDIALPARAMS. Unless these parameters are set by either lineMakeCall or lineSetCallParams, their values are the same as the defaults used in the LINEDEVCAPS structure.
dwOrigin
Identifies where the call originated from. This member uses the following LINECALLORIGIN_ constants:
LINECALLORIGIN_OUTBOUND
The call is an outgoing call.
LINECALLORIGIN_INTERNAL
The call is incoming and originated internally (on the same PBX, for example).
LINECALLORIGIN_EXTERNAL
The call is incoming and originated externally.
LINECALLORIGIN_UNKNOWN
The call is an incoming call and its origin is currently unknown but may become known later.
LINECALLORIGIN_UNAVAIL
The call is an incoming call. Its origin is not available and can never become known for this call.
LINECALLORIGIN_CONFERENCE
The call handle is for a conference call, that is, the application's connection to the conference bridge in the switch.
dwReason
The reason why the call occurred. This member uses the following LINECALLREASON_ constants:
LINECALLREASON_DIRECT
A direct call.
LINECALLREASON_FWDBUSY
The call was forwarded from another extension that was busy at the time of the call.
LINECALLREASON_FWDNOANSWER
The call was forwarded from another extension that didn't answer the call after some number of rings.
LINECALLREASON_FWDUNCOND
The call was forwarded unconditionally from another number.
LINECALLREASON_PICKUP
The call was picked up from another extension.
LINECALLREASON_UNPARK
The call was retrieved as a parked call.
LINECALLREASON_REDIRECT
The call was redirected to this station.
LINECALLREASON_CALLCOMPLETION
The call was the result of a call completion request.
LINECALLREASON_TRANSFER
The call has been transferred from another number. Party identifier information may indicate who the caller is and where the call was transferred from.
LINECALLREASON_REMINDER
The call is a reminder (or "recall") that the user has a call parked or on hold for a potentially long time.
LINECALLREASON_UNKNOWN
The reason for the call is currently unknown but may become known later.
LINECALLREASON_UNAVAIL
The reason for the call is unavailable and cannot become known later.
dwCompletionID
The completion identifier for the incoming call if it is the result of a completion request that terminates. This identifier is meaningful only if dwReason is LINECALLREASON_CALLCOMPLETION.
dwNumOwners
The number of application modules with different call handles with owner privilege for the call.
dwNumMonitors
The number of application modules with different call handles with monitor privilege for the call.
dwCountryCode
The country code of the destination party. Zero if unknown.
dwTrunk
The number of the trunk over which the call is routed. This member is used for both incoming and outgoing calls. The dwTrunk member should be set to 0xFFFFFFFF if it is unknown.
dwCallerIDFlags
Determines the validity and content of the caller party identifier information. The caller is the originator of the call. This member uses the following LINECALLPARTYID_ constants:
LINECALLPARTYID_BLOCKED
Caller ID information for the call has been blocked by the caller but would otherwise have been available.
LINECALLPARTYID_OUTOFAREA
Caller ID information for the call is not available because it is not propagated all the way by the network.
LINECALLPARTYID_NAME
The caller ID information for the call is the caller's name (from a table maintained inside the switch). It is provided in the caller ID name variably sized field.
LINECALLPARTYID_ADDRESS
The caller ID information for the call is the caller's number and is provided in the caller ID variably sized field.
LINECALLPARTYID_PARTIAL
Caller ID information for the call is valid but is limited to partial number information.
LINECALLPARTYID_UNKNOWN
Caller ID information is currently unknown but it may become known later.
LINECALLPARTYID_UNAVAIL
Caller ID information is unavailable and cannot become known later.
dwCallerIDSize
dwCallerIDOffset
The size in bytes of the variably sized field containing the caller party ID number information, and the offset in bytes from the beginning of this data structure.
dwCallerIDNameSize
dwCallerIDNameOffset
The size in bytes of the variably sized field containing the caller party ID name information, and the offset in bytes from the beginning of this data structure.
dwCalledIDFlags
Determines the validity and content of the called-party ID information. The called party corresponds to the originally addressed party. This member uses the following LINECALLPARTYID_ constants:
LINECALLPARTYID_BLOCKED
Called ID information for the call has been blocked by the caller but would otherwise have been available.
LINECALLPARTYID_OUTOFAREA
Caller ID information for the call is not available because it is not propagated all the way by the network.
LINECALLPARTYID_NAME
The called ID information for the call is the caller's name (from a table maintained inside the switch). It is provided in the called ID name variably sized field.
LINECALLPARTYID_ADDRESS
The called ID information for the call is the caller's number and is provided in the called ID variably sized field.
LINECALLPARTYID_PARTIAL
Called ID information for the call is valid but is limited to partial number information.
LINECALLPARTYID_UNKNOWN
Called ID information is currently unknown but it may become known later.
LINECALLPARTYID_UNAVAIL
Called ID information is unavailable and cannot become known later.
dwCalledIDSize
dwCalledIDOffset
The size in bytes of the variably sized field containing the called-party ID number information, and the offset in bytes from the beginning of this data structure.
dwCalledIDNameSize
dwCalledIDNameOffset
The size in bytes of the variably sized field containing the called-party ID name information, and the offset in bytes from the beginning of this data structure.
dwConnectedIDFlags
Determines the validity and content of the connected party ID information. The connected party is the party that was actually connected to. This may be different from the called-party ID if the call was diverted. This member uses the following LINECALLPARTYID_ constants:
LINECALLPARTYID_BLOCKED
Connected party identifier information for the call has been blocked by the caller but would otherwise have been available.
LINECALLPARTYID_OUTOFAREA
Connected identifier information for the call is not available as it is not propagated all the way by the network.
LINECALLPARTYID_NAME
The connected party identifier information for the call is the caller's name (from a table maintained inside the switch). It is provided in the connected identifier name variably sized field.
LINECALLPARTYID_ADDRESS
The connected party identifier information for the call is the caller's number and is provided in the connected identifier variably sized field.
LINECALLPARTYID_PARTIAL
Connected party identifier information for the call is valid but is limited to partial number information.
LINECALLPARTYID_UNKNOWN
Connected party identifier information is currently unknown but it may become known later.
LINECALLPARTYID_UNAVAIL
Connected party identifier information is unavailable and cannot become known later.
dwConnectedIDSize
dwConnectedIDOffset
The size in bytes of the variably sized field containing the connected party identifier number information, and the offset in bytes from the beginning of this data structure.
dwConnectedIDNameSize
dwConnectedIDNameOffset
The size in bytes of the variably sized field containing the connected party identifier name information, and the offset in bytes from the beginning of this data structure.
dwRedirectionIDFlags
Determines the validity and content of the redirection party identifier information. The redirection party identifies to the calling user the number toward which diversion was invoked. This member uses the following LINECALLPARTYID_ constants:
LINECALLPARTYID_BLOCKED
Redirection party identifier information for the call has been blocked by the caller but would otherwise have been available.
LINECALLPARTYID_OUTOFAREA
Redirection identifier information for the call is not available because it is not propagated all the along the network.
LINECALLPARTYID_NAME
The redirection party identifier information for the call is the caller's name (from a table maintained inside the switch). It is provided in the redirection identifier name variably sized field.
LINECALLPARTYID_ADDRESS
The redirection party identifier information for the call is the caller's number and is provided in the redirection identifier variably sized field.
LINECALLPARTYID_PARTIAL
Redirection party identifier information for the call is valid but is limited to partial number information.
LINECALLPARTYID_UNKNOWN
Redirection identifier information is currently unknown but it may become known later.
LINECALLPARTYID_UNAVAIL
Redirection identifier information is unavailable and cannot become known later.
dwRedirectionIDSize
dwRedirectionIDOffset
The size in bytes of the variably sized field containing the redirection party identifier number information, and the offset in bytes from the beginning of this data structure.
dwRedirectionIDNameSize
dwRedirectionIDNameOffset
The size in bytes of the variably sized field containing the redirection party identifier name information, and the offset in bytes from the beginning of this data structure.
dwRedirectingIDFlags
Determines the validity and content of the redirecting party identifier information. The party that received the call identifies the new destination number or whatever information is detected to the call originator. This member uses the following LINECALLPARTYID_ constants:
LINECALLPARTYID_BLOCKED
Redirecting party identifier information for the call has been blocked by the caller but would otherwise have been available.
LINECALLPARTYID_OUTOFAREA
Redirecting identifier information for the call is not available because it is not propagated all the way by the network.
LINECALLPARTYID_NAME
The redirecting party identifier information for the call is the caller's name (from a table maintained inside the switch). It is provided in the redirecting identifier name variably sized field.
LINECALLPARTYID_ADDRESS
The redirecting party identifier information for the call is the caller's number and is provided in the redirecting identifier variably sized field.
LINECALLPARTYID_PARTIAL
Redirecting party identifier information for the call is valid but is limited to partial number information.
LINECALLPARTYID_UNKNOWN
Redirecting identifier information is currently unknown but it may become known later.
LINECALLPARTYID_UNAVAIL
Redirecting identifier information is unavailable and cannot become known later.
dwRedirectingIDSize
dwRedirectingIDOffset
The size in bytes of the variably sized field containing the redirecting party identifier number information, and the offset in bytes from the beginning of this data structure.
dwRedirectingIDNameSize
dwRedirectingIDNameOffset
The size in bytes of the variably sized field containing the redirecting party identifier name information, and the offset in bytes from the beginning of this data structure.
dwAppNameSize
dwAppNameOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field holding the user-friendly application name of the application that first originated, accepted, or answered the call. This is the name that an application can specify in lineInitializeEx. If the application specifies no such name, then the application's module filename is used instead.
dwDisplayableAddressSize
dwDisplayableAddressOffset
The displayable string is used for logging purposes. The information is obtained from LINECALLPARAMS for functions that initiate calls. The lineTranslateAddress function returns appropriate information to be placed in this field in the dwDisplayableAddressSize and dwDisplayableAddressOffset members of the LINETRANSLATEOUTPUT structure.
dwCalledPartySize
dwCalledPartyOffset
The size in bytes of the variably sized field holding a user-friendly description of the called party, and the offset in bytes from the beginning of this data structure. This information can be specified with lineMakeCall and can be optionally specified in the lpCallParams parameter whenever a new call is established. It is useful for call logging purposes.
dwCommentSize
dwCommentOffset
The size in bytes of the variably sized field holding a comment about the call provided by the application that originated the call using lineMakeCall, and the offset in bytes from the beginning of this data structure. This information can be optionally specified in the lpCallParams parameter whenever a new call is established.
dwDisplaySize
dwDisplayOffset
The size in bytes of the variably sized field holding raw display information, and the offset in bytes from the beginning of this data structure. Depending on the telephony environment, a service provider may extract functional information from this member pair for formatting and presentation most appropriate for this telephony configuration.
dwUserUserInfoSize
dwUserUserInfoOffset
The size in bytes of the variably sized field holding user-user information, and the offset in bytes from the beginning of this data structure The protocol discriminator field for the user-user information, if used, appears as the first byte of the data pointed to by dwUserUserInfoOffset, and is accounted for in dwUserUserInfoSize.
dwHighLevelCompSize
dwHighLevelCompOffset
The size in bytes of the variably sized field holding high-level compatibility information, and the offset in bytes from the beginning of this data structure. The format of this information is specified by other standards (ISDN Q.931).
dwLowLevelCompSize
dwLowLevelCompOffset
The size in bytes of the variably sized field holding low-level compatibility information, and the offset in bytes from the beginning of this data structure. The format of this information is specified by other standards (ISDN Q.931).
dwChargingInfoSize
dwChargingInfoOffset
The size in bytes of the variably sized field holding charging information, and the offset in bytes from the beginning of this data structure. The format of this information is specified by other standards (ISDN Q.931).
dwTerminalModesSize
dwTerminalModesOffset
The size in bytes of the variably sized device field containing an array with DWORD-sized entries, and the offset in bytes from the beginning of this data structure. The set of LINETERMMODE_ constants is indexed by terminal identifiers, in the range from zero to one less than dwNumTerminals. Each entry in the array specifies the current terminal modes for the corresponding terminal set with the lineSetTerminal function for this call's media stream. Values are:
LINETERMMODE_LAMPS
Lamp events sent from the line to the terminal.
LINETERMMODE_BUTTONS
Button-press events sent from the terminal to the line.
LINETERMMODE_DISPLAY
Display information sent from the line to the terminal.
LINETERMMODE_RINGER
Ringer-control information sent from the switch to the terminal.
LINETERMMODE_HOOKSWITCH
Hookswitch event sent between the terminal and the line.
LINETERMMODE_MEDIATOLINE
The unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIAFROMLINE
The unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIABIDIRECT
The bidirectional media stream associated with a call on the line and the terminal. Use this value when the routing of both the unidirectional channels of a call's media stream cannot be controlled independently.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes of the variably sized field holding device-specific information., and the offset in bytes from the beginning of this data structure.
dwCallTreatment
The call treatment currently being applied on the call or that is applied when the call enters the next applicable state. Can be zero if call treatments are not supported.
dwCallDataSize
dwCallDataOffset
The size in bytes and offset from the beginning of LINECALLINFO of the application-settable call data.
dwSendingFlowspecSize
dwSendingFlowspecOffset
The total size in bytes and offset from the beginning of LINECALLINFO of a WinSock2 FLOWSPEC structure followed by WinSock2 provider-specific data, equivalent to what would have been stored in SendingFlowspec.len in a WinSock2 QOS structure. Specifies the quality of service current in effect in the sending direction on the call. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory, because TAPI does not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the application.
dwReceivingFlowspecSize
dwReceivingFlowspecOffset
The total size in bytes and offset from the beginning of LINECALLINFO of a WinSock2 FLOWSPEC structure followed by WinSock2 provider-specific data, equivalent to what would have been stored in ReceivingFlowspec.len in a WinSock2 QOS structure. Specifies the quality of service current in effect in the receiving direction on the call. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory, because TAPI does not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the application.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

The LINECALLINFO data structure contains relatively fixed information about a call. This structure is returned with lineGetCallInfo. When information items in this data structure have changed, a LINE_CALLINFO message is sent to the application. A parameter to this message is the information item or field that changed.

The members dwCallTreatment through dwReceivingFlowspecOffset are available only to applications that open the line device with an API version of 2.0 or later.

Note The preferred format for specification of the contents of the dwCallID field and the other five similar fields (dwCallerIDFlag, dwCallerIDSize, dwCallerIDOffset, dwCallerIDNameSize, and dwCallerIDNameOffset) is the TAPI canonical number format. For example, a ICLID of "4258828080" received from the switch should be converted to "+1 (425) 8828080" before being placed in the LINECALLINFO structure. This standardized format facilitates searching of databases and callback functions implemented in applications.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINE_CALLINFO, LINE_MONITORMEDIA, LINECALLSTATUS, LINEDEVCAPS, LINEDIALPARAMS, lineGenerateDigits, lineGetCallInfo, lineGetCallStatus, lineInitializeEx, lineMakeCall, lineSecureCall, lineSetAppSpecific, lineSetCallParams, lineSetTerminal, lineTranslateAddress, LINETRANSLATEOUTPUT


LINECALLLIST

The LINECALLLIST structure describes a list of call handles. A structure of this type is returned by the lineGetNewCalls and lineGetConfRelatedCalls functions.

typedef struct linecalllist_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwCallsNumEntries;
    DWORD  dwCallsSize;
    DWORD  dwCallsOffset;
} LINECALLLIST, FAR *LPLINECALLLIST;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwCallsNumEntries
The number of handles in the hCalls array.
dwCallsSize
dwCallsOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field (which is an array of HCALL-sized handles).

Remarks

No extensions.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

lineGetConfRelatedCalls, lineGetNewCalls


LINECALLPARAMS

The LINECALLPARAMS structure describes parameters supplied when making calls using lineMakeCall. The LINECALLPARAMS structure is also used as a parameter in other operations. The comments on the right indicate the default values used when this structure is not provided to lineMakeCall.

typedef struct linecallparams_tag {  // Defaults:
    DWORD  dwTotalSize;          // ---------

    DWORD  dwBearerMode;              // voice
    DWORD  dwMinRate;                 // (3.1kHz)
    DWORD  dwMaxRate;                 // (3.1kHz)
    DWORD  dwMediaMode;               // interactiveVoice

    DWORD  dwCallParamFlags;          // 0
    DWORD  dwAddressMode;             // addressID
    DWORD  dwAddressID;               // (any available)

  LINEDIALPARAMS DialParams;        // (0, 0, 0, 0)

    DWORD  dwOrigAddressSize;         // 0
    DWORD  dwOrigAddressOffset;

    DWORD  dwDisplayableAddressSize;  // 0
    DWORD  dwDisplayableAddressOffset;

    DWORD  dwCalledPartySize;         // 0
    DWORD  dwCalledPartyOffset;

    DWORD  dwCommentSize;             // 0
    DWORD  dwCommentOffset;

    DWORD  dwUserUserInfoSize;        // 0
    DWORD  dwUserUserInfoOffset;

    DWORD  dwHighLevelCompSize;       // 0
    DWORD  dwHighLevelCompOffset;

    DWORD  dwLowLevelCompSize;        // 0
    DWORD  dwLowLevelCompOffset;

    DWORD  dwDevSpecificSize;         // 0
    DWORD  dwDevSpecificOffset;

    DWORD  dwPredictiveAutoTransferStates;
    DWORD  dwTargetAddressSize;
    DWORD  dwTargetAddressOffset;
    DWORD  dwSendingFlowspecSize;
    DWORD  dwSendingFlowspecOffset;
    DWORD  dwReceivingFlowspecSize;
    DWORD  dwReceivingFlowspecOffset;
    DWORD  dwDeviceClassSize;
    DWORD  dwDeviceClassOffset;
    DWORD  dwDeviceConfigSize;
    DWORD  dwDeviceConfigOffset;
    DWORD  dwCallDataSize;
    DWORD  dwCallDataOffset;
    DWORD  dwNoAnswerTimeout;
    DWORD  dwCallingPartyIDSize;
    DWORD  dwCallingPartyIDOffset;
} LINECALLPARAMS, FAR *LPLINECALLPARAMS;

Members

dwTotalSize
The total size in bytes allocated to this data structure. This size should be big enough to hold all the fixed and variably sized portions of this data structure.
dwBearerMode
The bearer mode for the call. This member uses the following LINEBEARERMODE_ constants:
LINEBEARERMODE_VOICE
This is a regular 3.1 kHz analog voice grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.
LINEBEARERMODE_SPEECH
Corresponds to G.711 speech transmission on the call. The network can use processing techniques such as analog transmission, echo cancellation, and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.
LINEBEARERMODE_MULTIUSE
The multiuse mode defined by ISDN.
LINEBEARERMODE_DATA
The unrestricted data transfer on the call. The data rate is specified separately.
LINEBEARERMODE_ALTSPEECHDATA
The alternate transfer of speech or unrestricted data on the same call (ISDN).
LINEBEARERMODE_NONCALLSIGNALING
Corresponds to a non-call-associated signaling connection from the application to the service provider or switch (treated as a "media stream" by the Telephony API).
LINEBEARERMODE_PASSTHROUGH
When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 comm functions, for the purpose of configuring or using special features not otherwise supported by the service provider.

If dwBearerMode is zero, the default value is LINEBEARERMODE_VOICE.

dwMinRate
dwMaxRate
The data rate range requested for the call's data stream in bps (bits per second). When making a call, the service provider attempts to provide the highest available rate in the requested range. If a specific data rate is required, both min and max should be set to that value. If an application works best with one rate but is able to degrade to lower rates, the application should specify these as the maximum and minimum rates, respectively. If dwMaxRate is zero, the default value is as specified by the dwMaxRate member of the LINEDEVCAPS structure. This is the maximum rate supported by the device.
dwMediaMode
The expected media mode of the call. This member uses the following LINEMEDIAMODE_ constants:
LINEMEDIAMODE_UNKNOWN
A media stream exists but its mode is not known. This would correspond to a call with an unclassified media type. In typical analog telephony environments, an incoming call's media mode may be unknown until after the call has been answered and the media stream has been filtered to make a determination.
LINEMEDIAMODE_INTERACTIVEVOICE
The presence of voice energy on the call and the call is treated as an interactive call with humans on both ends.
LINEMEDIAMODE_AUTOMATEDVOICE
The presence of voice energy on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM
A datamodem session on the call.
LINEMEDIAMODE_G3FAX
A group 3 fax is being sent or received on the call.
LINEMEDIAMODE_G4FAX
A group 4 fax is being sent or received on the call.
LINEMEDIAMODE_TDD
A TDD (Telephony Devices for the Deaf) session on the call.
LINEMEDIAMODE_DIGITALDATA
Digital data is being sent or received on the call.
LINEMEDIAMODE_TELETEX
A teletex session on the call. Teletex is one of the telematic services.
LINEMEDIAMODE_VIDEOTEX
A videotex session on the call. Videotex is one of the telematic services.
LINEMEDIAMODE_TELEX
A telex session on the call. Telex is one of the telematic services.
LINEMEDIAMODE_MIXED
A mixed session on the call. Mixed is one of the ISDN telematic services.
LINEMEDIAMODE_ADSI
An ADSI (Analog Display Services Interface) session on the call.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.

If dwMediaMode is zero, the default value is LINEMEDIAMODE_INTERACTIVEVOICE.

dwCallParamFlags
These flags specify a collection of Boolean call-setup parameters. This member uses the following LINECALLPARAMFLAGS_ constants:
LINECALLPARAMFLAGS_SECURE
The call should be set up as secure.
LINECALLPARAMFLAGS_IDLE
The call should get an idle call appearance.
LINECALLPARAMFLAGS_BLOCKID
The originator identity should be concealed (block caller ID).
LINECALLPARAMFLAGS_ORIGOFFHOOK
The originator's phone should be automatically taken offhook.
LINECALLPARAMFLAGS_DESTOFFHOOK
The called party's phone should be automatically taken offhook.
dwAddressMode
The mode by which the originating address is specified. The dwAddressMode member cannot be LINEADDRESSMODE_ADDRESSID for the lineOpen function call. This member uses the following LINEADDRESSMODE_ constants:
LINEADDRESSMODE_ADDRESSID
The address is specified with a small integer in the range zero to dwNumAddresses minus one, where dwNumAddresses is the value in the line's LINEDEVCAPS structure. The selected address is specified in the dwAddressID member.
LINEADDRESSMODE_DIALABLEADDR
The address is specified with its dialable address. The address is contained in the dwOrigAddressSize dwOrigAddressOffset variably sized field. If dwAddressMode is zero, the default value is LINEADDRESSMODE_ADDRESSID.
dwAddressID
The address identifier of the originating address if dwAddressMode is set to LINEADDRESSMODE_ADDRESSID.
DialParams
Dial parameters to be used on this call, of type LINEDIALPARAMS. When a value of 0 is specified for this field, the default value for the field is used as indicated in the DefaultDialParams member of the LINEDEVCAPS structure. If a nonzero value is specified for a field that is outside the range specified by the corresponding fields in MinDialParams and MaxDialParams in the LINEDEVCAPS structure, the nearest value within the valid range is used instead.
dwOrigAddressSize
dwOrigAddressOffset
The size in bytes of the variably sized field holding the originating address, and the offset in bytes from the beginning of this data structure. The format of this address is dependent on the dwAddressMode member.
dwDisplayableAddressSize
dwDisplayableAddressOffset
The displayable string is used for logging purposes. The content of these members is recorded in the dwDisplayableAddressOffset and dwDisplayableAddressSize members of the call's LINECALLINFO message. The lineTranslateAddress function returns appropriate information to be placed in this field in the dwDisplayableAddressSize and dwDisplayableAddressOffset members of the LINETRANSLATEOUTPUT structure.
dwCalledPartySize
dwCalledPartyOffset
The size in bytes of the variably sized field holding called-party information, and the offset in bytes from the beginning of this data structure. This information can be specified by the application that makes the call and is made available in the call's information structure for logging purposes. The format of this field is that of dwStringFormat, as specified in LINEDEVCAPS.
dwCommentSize
dwCommentOffset
The size in bytes of the variably sized field holding comments about the call, and the offset in bytes from the beginning of this data structure. This information can be specified by the application that makes the call and is made available in the call's information structure for logging purposes. The format of this field is that of dwStringFormat, as specified in LINEDEVCAPS.
dwUserUserInfoSize
dwUserUserInfoOffset
The size in bytes of the variably sized field holding user-user information, and the offset in bytes from the beginning of this data structure. The protocol discriminator field for the user-user information, if required, should appear as the first byte of the data pointed to by dwUserUserInfoOffset, and must be accounted for in dwUserUserInfoSize.
dwHighLevelCompSize
dwHighLevelCompOffset
The size in bytes of the variably sized field holding high-level compatibility information, and the offset in bytes from the beginning of this data structure
dwLowLevelCompSize
dwLowLevelCompOffset
The size in bytes of the variably sized field holding low-level compatibility information, and the offset in bytes from the beginning of this data structure.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes of the variably sized field holding device-specific information, and the offset in bytes from the beginning of this data structure
dwPredictiveAutoTransferStates
The LINECALLSTATE_ values, entry into which cause the call to be blind-transferred to the specified target address. Set to zero if automatic transfer is not desired.
dwTargetAddressSize
dwTargetAddressOffset
The size in bytes and offset from the beginning of LINECALLPARAMS of a string specifying the target dialable address (not dwAddressID); used in the case of certain automatic actions. In the case of predictive dialing, specifies the address to which the call should be automatically transferred. This is essentially the same string that would be passed to lineBlindTransfer if automatic transfer were not being used. Set to zero if automatic transfer is not desired. In the case of a No Hold Conference, specifies the address that should be conferenced to the call. In the case of a One Step Transfer, specifies the address to dial on the consultation call.
dwSendingFlowspecSize
dwSendingFlowspecOffset
The total size in bytes and offset from the beginning of LINECALLPARAMS of a WinSock2 FLOWSPEC structure followed by WinSock2 provider-specific data, equivalent to what would have been stored in SendingFlowspec.len in a WinSock2 QOS structure. Specifies the quality of service desired in the sending direction on the call. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory, because TAPI does not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the application.
dwReceivingFlowspecSize
dwReceivingFlowspecOffset
The total size in bytes and offset from the beginning of LINECALLPARAMS of a WinSock2 FLOWSPEC structure followed by WinSock2 provider-specific data, equivalent to what would have been stored in ReceivingFlowspec.len in a WinSock2 QOS structure. Specifies the quality of service desired in the receiving direction on the call. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory, because TAPI does not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the application.
dwDeviceClassSize
dwDeviceClassOffset
The size in bytes and offset from the beginning of LINECALLPARAMS of a NULL-terminated ASCII string (the size includes the NULL) that indicates the device class of the device whose configuration is specified in DeviceConfig. Valid device class strings are the same as those specified for the lineGetID function.
dwDeviceConfigSize
dwDeviceConfigOffset
The number of bytes and offset from the beginning of LINECALLPARAMS of the opaque configuration data structure pointed to by dwDevConfigOffset. This value is returned in the dwStringSize member in the VARSTRING structure returned by lineGetDevConfig. If the size is zero, the default device configuration is used. This allows the application to set the device configuration before the call is initiated.
dwCallDataSize
dwCallDataOffset
The size in bytes and offset from the beginning of LINECALLPARAMS of the application-settable call data to be initially attached to the call.
dwNoAnswerTimeout
The number of seconds, after the completion of dialing, that the call should be allowed to wait in the PROCEEDING or RINGBACK states, before it is automatically abandoned by the service provider with a LINECALLSTATE_DISCONNECTED and LINEDISCONNECTMODE_NOANSWER. A value of 0 indicates that the application does not desire automatic call abandonment.
dwCallingPartyIDSize
dwCallingPartyIDOffset
The size in bytes and offset from the beginning of LINECALLPARAMS of a NULL-terminated ASCII string (the size includes the NULL) that specifies the identity of the party placing the call. If the content of the identifier is acceptable and a path is available, the service provider passes the identifier along to the called party to indicate the identity of the calling party.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

This structure is used as a parameter to lineMakeCall when setting up a call. Its fields allow the application to specify the quality of service requested from the network as well as a variety of ISDN call-setup parameters. If no LINECALLPARAMS structure is supplied to lineMakeCall, a default POTS voice-grade call is requested with the default values listed above.

Note The fields DialParams through dwDevSpecificOffset are ignored when an lpCallParams parameter is specified with the lineOpen function.

The members dwPredictiveAutoTransferStates through dwCallingPartyIDOffset are available only to applications that open the line device with an API version of 2.0 or later.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

lineBlindTransfer, LINEDEVCAPS, LINEDIALPARAMS, lineGetDevConfig, lineGetID, lineMakeCall, lineOpen, lineTranslateAddress, LINETRANSLATEOUTPUT, VARSTRING


LINECALLSTATUS

The LINECALLSTATUS structure describes the current status of a call. The information in this structure, as returned with lineGetCallStatus, depends on the device capabilities of the address, the ownership of the call by the invoking application, and the current state of the call being queried.

typedef struct linecallstatus_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwCallState;
    DWORD  dwCallStateMode;
    DWORD  dwCallPrivilege;
    DWORD  dwCallFeatures;

    DWORD  dwDevSpecificSize;
    DWORD  dwDevSpecificOffset;

    DWORD  dwCallFeatures2;
    SYSTEMTIME  tStateEntryTime;
} LINECALLSTATUS, FAR *LPLINECALLSTATUS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwCallState
dwCallStateMode
The dwCallState member specifies the current call state of the call. The interpretation of the dwCallStateMode member is call-state-dependent. It specifies the current mode of the call while in its current state (if that state defines a mode). This member uses the following LINECALLSTATE_ constants:
LINECALLSTATE_IDLE
The call state mode is unused.
LINECALLSTATE_OFFERING
The call state mode is of type LINEOFFERINGMODE_. Values are:
LINEOFFERINGMODE_ACTIVE
Indicates that the call is alerting at the current station (is accompanied by LINEDEVSTATE_RINGING messages), and if any application is set up to automatically answer, it may do so.
LINEOFFERINGMODE_INACTIVE
Indicates that the call is being offered at more than one station, but the current station is not alerting (for example, it may be an attendant station where the offering status is advisory, such as a blinking light).
LINECALLSTATE_ACCEPTED
The call state mode is unused.
LINECALLSTATE_DIALTONE
The call state mode is of type LINEDIALTONEMODE_. Values are:
LINEDIALTONEMODE_NORMAL
A "normal" dial tone, which typically is a continuous tone.
LINEDIALTONEMODE_SPECIAL
A special dial tone indicating a certain condition is currently in effect.
LINEDIALTONEMODE_INTERNAL
An internal dial tone, as within a PBX.
LINEDIALTONEMODE_EXTERNAL
An external (public network) dial tone.
LINEDIALTONEMODE_UNKNOWN
The dial tone mode is not currently known but may become known later.
LINEDIALTONEMODE_UNAVAIL
The dial tone mode is unavailable and cannot become known.
LINECALLSTATE_DIALING
Call state mode is unused.
LINECALLSTATE_RINGBACK
Call state mode is unused.
LINECALLSTATE_BUSY
The call state mode is of type LINEBUSYMODE_. Values are:
LINEBUSYMODE_STATION
The busy signal indicates that the called party's station is busy. This is usually signaled with a "normal" busy tone.
LINEBUSYMODE_TRUNK
The busy signal indicates that a trunk or circuit is busy. This is usually signaled with a "long" busy tone.
LINEBUSYMODE_UNKNOWN
The busy signal's specific mode is currently unknown but may become known later.
LINEBUSYMODE_UNAVAIL
The busy signal's specific mode is unavailable and cannot become known.
LINECALLSTATE_SPECIALINFO
The call state mode is of type LINESPECIALINFO_. Values are:
LINESPECIALINFO_NOCIRCUIT
Special information tone that precedes a no-circuit or emergency announcement (trunk blockage category).
LINESPECIALINFO_CUSTIRREG
Special information tone that precedes a vacant number, AIS, Centrex number change and nonworking station, access code not dialed or dialed in error, or manual intercept operator message (customer irregularity category).
LINESPECIALINFO_REORDER
Special information tone that precedes a reorder announcement (equipment irregularity category).
LINESPECIALINFO_UNKNOWN
Specifics about the special information tone are currently unknown but may become known later.
LINESPECIALINFO_UNAVAIL
Specifics about the special information tone are unavailable and cannot become known.
LINECALLSTATE_CONNECTED
Call state mode is of type LINECONNECTEDMODE_. Values are:
LINECONNECTEDMODE_ACTIVE
Indicates that the call is connected at the current station (the current station is a participant in the call).
LINECONNECTEDMODE_INACTIVE
Indicates that the call is active at one or more other stations, but the current station is not a participant in the call.
LINECALLSTATE_PROCEEDING
Call state mode is unused.
LINECALLSTATE_ONHOLD
Call state mode is unused.
LINECALLSTATE_CONFERENCED
Call state mode is unused.
LINECALLSTATE_ONHOLDPENDCONF
Call state mode is unused.
LINECALLSTATE_ONHOLDPENDTRANSF
Call state mode is unused.
LINECALLSTATE_DISCONNECTED
Call state mode is of type LINEDISCONNECTMODE_. Values are:
LINEDISCONNECTMODE_NORMAL
This is a "normal" disconnect request by the remote party. The call was terminated normally.
LINEDISCONNECTMODE_UNKNOWN
The reason for the disconnect request is unknown.
LINEDISCONNECTMODE_REJECT
The remote user has rejected the call.
LINEDISCONNECTMODE_PICKUP
The call was picked up from elsewhere.
LINEDISCONNECTMODE_FORWARDED
The call was forwarded by the switch.
LINEDISCONNECTMODE_BUSY
The remote user's station is busy.
LINEDISCONNECTMODE_NOANSWER
The remote user's station does not answer.
LINEDISCONNECTMODE_NODIALTONE
A dial tone was not detected within a service provider-defined timeout, at a point during dialing when one was expected (such as at a "W" in the dialable string). This can also occur without a service provider-defined timeout period or without a value specified in the dwWaitForDialTone member of the LINEDIALPARAMS structure.
LINEDISCONNECTMODE_BADADDRESS
The destination address in invalid.
LINEDISCONNECTMODE_UNREACHABLE
The remote user could not be reached.
LINEDISCONNECTMODE_CONGESTION
The network is congested.
LINEDISCONNECTMODE_INCOMPATIBLE
The remote user's station equipment is incompatible with the type of call requested.
LINEDISCONNECTMODE_UNAVAIL
The reason for the disconnect is unavailable and cannot become known later.
LINECALLSTATE_UNKNOWN
Call state mode is unused.
dwCallPrivilege
The application's privilege for this call. This member uses the following LINECALLPRIVILEGE_ constants. Values are:
LINECALLPRIVILEGE_MONITOR
The application has monitor privilege.
LINECALLPRIVILEGE_OWNER
The application has owner privilege.
dwCallFeatures
These flags indicate the Telephony API functions that can be invoked on the call, given the availability of the feature in the device capabilities, the current call state, and call ownership of the invoking application. A zero indicates the corresponding feature cannot be invoked by the application on the call in its current state; a one indicates the feature can be invoked. This member uses LINECALLFEATURE_ constants.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes of the variably sized device-specific field, and the offset in bytes from the beginning of this data structure.
dwCallFeatures2
Indicates additional functions can be invoked on the call, given the availability of the feature in the device capabilities, the current call state, and call ownership of the invoking application. An extension of the dwCallFeatures member. This member uses LINECALLFEATURE2_ constants.
tStateEntryTime
The Coordinated Universal Time at which the current call state was entered.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

The application is sent a LINE_CALLSTATE message whenever the call state of a call changes. This message only provides the new call state of the call. Additional status about a call is available with lineGetCallStatus.

The members dwCallFeatures2 and tStateEntryTime are available only to applications that open the line device with an API version of 2.0 or later.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINE_CALLSTATE, LINEDIALPARAMS, lineGetCallStatus


LINECALLTREATMENTENTRY

typedef struct linecalltreatmententry_tag {
    DWORD  dwCallTreatmentID;
    DWORD  dwCallTreatmentNameSize;
    DWORD  dwCallTreatmentNameOffset;
} LINECALLTREATMENTENTRY, FAR *LPLINECALLTREATMENTENTRY;

Members

dwCallTreatmentID
One of the LINECALLTREATMENT_ constants (if the treatment is of a predefined type) or a service provider-specific value.
dwCallTreatmentNameSize
dwCallTreatmentNameOffset
Size in bytes (including the terminating NULL) and offset from the beginning of LINEADDRESSCAPS of a NULL-terminated string identifying the treatment. This would ordinarily describe the content of the music or recorded announcement. If the treatment is of a predefined type, a meaningful name should still be specified, for example, "Silence\0", "Busy Signal\0", "Ringback\0", or "Music\0".

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.


LINECARDENTRY

The LINECARDENTRY structure describes a calling card.

typedef struct linecardentry_tag {
    DWORD  dwPermanentCardID;
    DWORD  dwCardNameSize;
    DWORD  dwCardNameOffset;
    DWORD  dwCardNumberDigits;
    DWORD  dwSameAreaRuleSize;
    DWORD  dwSameAreaRuleOffset;
    DWORD  dwLongDistanceRuleSize;
    DWORD  dwLongDistanceRuleOffset;
    DWORD  dwInternationalRuleSize;
    DWORD  dwInternationalRuleOffset;
    DWORD  dwOptions;
} LINECARDENTRY, FAR *LPLINECARDENTRY;

Members

dwPermanentCardID
The permanent identifier that identifies the card.
dwCardNameSize
dwCardNameOffset
Contains a NULL-terminated ASCII string (size includes the NULL) that describes the card in a user-friendly manner.
dwCardNumberDigits
The number of digits in the existing card number. The card number itself is not returned for security reasons (it is stored in scrambled form by TAPI). The application can use this to insert filler bytes into a text control in "password" mode to show that a number exists.
dwSameAreaRuleSize
dwSameAreaRuleOffset
The offset in bytes from the beginning of the LINETRANSLATECAPS structure and the total number of bytes in the dialing rule defined for calls to numbers in the same area code. The rule is a NULL-terminated ASCII string.
dwLongDistanceRuleSize
dwLongDistanceRuleOffset
The offset in bytes from the beginning of the LINETRANSLATECAPS structure and the total number of bytes in the dialing rule defined for calls to numbers in the other areas in the same country. The rule is a NULL-terminated ASCII string.
dwInternationalRuleSize
dwInternationalRuleOffset
The offset in bytes from the beginning of the LINETRANSLATECAPS structure and the total number of bytes in the dialing rule defined for calls to numbers in other countries. The rule is a NULL-terminated ASCII string.
dwOptions
Indicates other settings associated with this calling card, using the LINECARDOPTION_ set of constants.

Remarks

Older applications are compiled without knowledge of these new fields, and using a SIZEOF LINECARDENTRY smaller than the new size. Because this is an array in the variable portion of a LINETRANSLATECAPS structure, it is imperative that older applications receive LINECARDENTRY structures in the format they previously expected, or they are not able to index properly through the array. The application passes in a dwAPIVersion parameter with the lineGetTranslateCaps function, which can be used for guidance by TAPI in handling this situation. The lineGetTranslateCaps function should use the LINECARDENTRY fields and size that match the indicated API version, when building the LINETRANSLATECAPS structure to be returned to the application.

No extensions.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

lineGetTranslateCaps, LINETRANSLATECAPS


LINECOUNTRYENTRY

The LINECOUNTRYENTRY structure provides the information for a single country entry. An array of one or more of these structures is returned as part of the LINECOUNTRYLIST structure, returned by the lineGetCountry function.

typedef struct linecountryentry_tag {
    DWORD  dwCountryID;
    DWORD  dwCountryCode;
    DWORD  dwNextCountryID;
    DWORD  dwCountryNameSize;
    DWORD  dwCountryNameOffset;
    DWORD  dwSameAreaRuleSize;
    DWORD  dwSameAreaRuleOffset;
    DWORD  dwLongDistanceRuleSize;
    DWORD  dwLongDistanceRuleOffset;
    DWORD  dwInternationalRuleSize;
    DWORD  dwInternationalRuleOffset;
} LINECOUNTRYENTRY, FAR *LPLINECOUNTRYENTRY;

Members

dwCountryID
The country identifier of the entry. The country identifier is an internal identifier that allows multiple entries to exist in the country list with the same country code (for example, all countries in North America and the Caribbean share country code 1, but require separate entries in the list).
dwCountryCode
The actual country code of the country represented by the entry (that is, the digits that would be dialed in an international call). Only this value should ever be displayed to users (country identifiers should never be displayed, as they would be confusing).
dwNextCountryID
The country identifier of the next entry in the country list. Because country codes and identifiers are not assigned in any regular numeric sequence, the country list is a single linked list, with each entry pointing to the next. The last country in the list has a dwNextCountryID value of zero. When the LINECOUNTRYLIST structure is used to obtain the entire list, the entries in the list are in sequence as linked by their dwNextCountryID members.
dwCountryNameSize
dwCountryNameOffset
The size in bytes and the offset in bytes from the beginning of the LINECOUNTRYLIST structure of a NULL-terminated string giving the name of the country.
dwSameAreaRuleSize
dwSameAreaRuleOffset
The size in bytes and the offset in bytes from the beginning of the LINECOUNTRYLIST structure of a NULL-terminated ASCII string containing the dialing rule for direct-dialed calls to the same area code.
dwLongDistanceRuleSize
dwLongDistanceRuleOffset
The size in bytes and the offset in bytes from the beginning of the LINECOUNTRYLIST structure of a NULL-terminated ASCII string containing the dialing rule for direct-dialed calls to other areas in the same country.
dwInternationalRuleSize
dwInternationalRuleOffset
The size in bytes and the offset in bytes from the beginning of the LINECOUNTRYLIST structure of a NULL-terminated ASCII string containing the dialing rule for direct-dialed calls to other countries.

Remarks

Not extensible.

Because this structure is returned by a new function, backward compatibility is not an issue at this time.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINECOUNTRYLIST, lineGetCountry


LINECOUNTRYLIST

The LINECOUNTRYLIST structure describes a list of countries. A structure of this type is returned by the lineGetCountry function.

typedef struct linecountrylist_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwNumCountries;
    DWORD  dwCountryListSize;
    DWORD  dwCountryListOffset;
} LINECOUNTRYLIST, FAR *LPLINECOUNTRYLIST;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwNumCountries
The number of LINECOUNTRYENTRY structures present in the array denominated by dwCountryListSize and dwCountryListOffset.
dwCountryListSize
dwCountryListOffset
The size in bytes and the offset in bytes from the beginning of this data structure of an array of LINECOUNTRYENTRY elements that provide the information on each country.

Remarks

Not extensible.

Because this structure is returned by a new function, backward compatibility is not an issue at this time.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINECOUNTRYENTRY, lineGetCountry


LINEDEVCAPS

The LINEDEVCAPS structure describes the capabilities of a line device.

typedef struct linedevcaps_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwProviderInfoSize;
    DWORD  dwProviderInfoOffset;

    DWORD  dwSwitchInfoSize;
    DWORD  dwSwitchInfoOffset;

    DWORD  dwPermanentLineID;
    DWORD  dwLineNameSize;
    DWORD  dwLineNameOffset;
    DWORD  dwStringFormat;
    DWORD  dwAddressModes;
    DWORD  dwNumAddresses;
    DWORD  dwBearerModes;
    DWORD  dwMaxRate;
    DWORD  dwMediaModes;

    DWORD  dwGenerateToneModes;
    DWORD  dwGenerateToneMaxNumFreq;
    DWORD  dwGenerateDigitModes;
    DWORD  dwMonitorToneMaxNumFreq;
    DWORD  dwMonitorToneMaxNumEntries;
    DWORD  dwMonitorDigitModes;
    DWORD  dwGatherDigitsMinTimeout;
    DWORD  dwGatherDigitsMaxTimeout;

    DWORD  dwMedCtlDigitMaxListSize;
    DWORD  dwMedCtlMediaMaxListSize;
    DWORD  dwMedCtlToneMaxListSize;
    DWORD  dwMedCtlCallStateMaxListSize;

    DWORD  dwDevCapFlags;
    DWORD  dwMaxNumActiveCalls;
    DWORD  dwAnswerMode;
    DWORD  dwRingModes;
    DWORD  dwLineStates;

    DWORD  dwUUIAcceptSize;
    DWORD  dwUUIAnswerSize;
    DWORD  dwUUIMakeCallSize;
    DWORD  dwUUIDropSize;
    DWORD  dwUUISendUserUserInfoSize;
    DWORD  dwUUICallInfoSize;

  LINEDIALPARAMS  MinDialParams;
  LINEDIALPARAMS  MaxDialParams;
  LINEDIALPARAMS  DefaultDialParams;

    DWORD  dwNumTerminals;
    DWORD  dwTerminalCapsSize;
    DWORD  dwTerminalCapsOffset;
    DWORD  dwTerminalTextEntrySize;
    DWORD  dwTerminalTextSize;
    DWORD  dwTerminalTextOffset;

    DWORD  dwDevSpecificSize;
    DWORD  dwDevSpecificOffset;

    DWORD  dwLineFeatures;

    DWORD  dwSettableDevStatus;
    DWORD  dwDeviceClassesSize;
    DWORD  dwDeviceClassesOffset;
} LINEDEVCAPS, FAR *LPLINEDEVCAPS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwProviderInfoSize
dwProviderInfoOffset
The size in bytes of the variably sized field containing service provider information, and the offset in bytes from the beginning of this data structure. The dwProviderInfoSize/Offset member is intended to provide information about the provider hardware and/or software, such as the vendor name and version numbers of hardware and software. This information can be useful when a user needs to call customer service with problems regarding the provider.
dwSwitchInfoSize
dwSwitchInfoOffset
The size in bytes of the variably sized device field containing switch information, and the offset in bytes from the beginning of this data structure. The dwSwitchInfoSize/Offset member is intended to provide information about the switch to which the line device is connected, such as the switch manufacturer, the model name, the software version, and so on. This information can be useful when a user needs to call customer service with problems regarding the switch.
dwPermanentLineID
The permanent DWORD identifier by which the line device is known in the system's configuration. It is a permanent name for the line device. This permanent name (as opposed to dwDevice ID) does not change as lines are added or removed from the system. It can therefore be used to link line-specific information in INI files (or other files) in a way that is not affected by adding or removing other lines.
dwLineNameSize
dwLineNameOffset
The size in bytes of the variably sized device field containing a user configurable name for this line device, and the offset in bytes from the beginning of this data structure. This name can be configured by the user when configuring the line device's service provider, and is provided for the user's convenience.
dwStringFormat
The string format used with this line device. This member uses the following STRINGFORMAT_ constants:
STRINGFORMAT_ASCII
The ASCII string format using one byte per character.
STRINGFORMAT_DBCS
The DBCS string format using one or two bytes per character.
STRINGFORMAT_UNICODE
The Unicode string format using two bytes per character.
dwAddressModes
The mode by which the originating address is specified. This member uses the LINEADDRESSMODE_ constants.
dwNumAddresses
The number of addresses associated with this line device. Individual addresses are referred to by address identifiers. Address identifiers range from zero to one less than the value indicated by dwNumAddresses.
dwBearerModes
Flag array that indicates the different bearer modes that the address is able to support. This member uses the following LINEBEARERMODE_ constants:
LINEBEARERMODE_VOICE
A regular 3.1 kHz analog voice-grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.
LINEBEARERMODE_SPEECH
Corresponds to G.711 speech transmission on the call. The network may use processing techniques such as analog transmission, echo cancellation and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.
LINEBEARERMODE_MULTIUSE
The multiuse mode defined by ISDN.
LINEBEARERMODE_DATA
The unrestricted data transfer on the call. The data rate is specified separately.
LINEBEARERMODE_ALTSPEECHDATA
The alternate transfer of speech or unrestricted data on the same call (ISDN).
LINEBEARERMODE_NONCALLSIGNALING
Corresponds to a non-call-associated signaling connection from the application to the service provider or switch (treated as a "media stream" by the Telephony API).
LINEBEARERMODE_PASSTHROUGH
When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 comm functions, for the purpose of configuring or using special features not otherwise supported by the service provider.
dwMaxRate
Contains the maximum data rate in bits per second for information exchange over the call.
dwMediaModes
Flag array that indicates the different media modes the address is able to support. This member uses the following LINEMEDIAMODE_ constants:
LINEMEDIAMODE_UNKNOWN
A media stream exists but its mode is not known. This corresponds to a call with an unclassified media type. In typical analog telephony environments, an incoming call's media mode may be unknown until after the call has been answered and the media stream filtered to make a determination.
LINEMEDIAMODE_INTERACTIVEVOICE
The presence of voice energy on the call and the call is treated as an interactive call with humans on both ends.
LINEMEDIAMODE_AUTOMATEDVOICE
The presence of voice energy on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM
A data modem session on the call.
LINEMEDIAMODE_G3FAX
A group 3 fax is being sent or received over the call.
LINEMEDIAMODE_G4FAX
A group 4 fax is being sent or received over the call.
LINEMEDIAMODE_TDD
A TDD (Telephony Devices for the Deaf) session on the call.
LINEMEDIAMODE_DIGITALDATA
Digital data being transmitted over the call.
LINEMEDIAMODE_TELETEX
A teletex session on the call. Teletex is one of the telematic services.
LINEMEDIAMODE_VIDEOTEX
A videotex session on the call. Videotex is one of the telematic services.
LINEMEDIAMODE_TELEX
A telex session on the call. Telex is one of the telematic services.
LINEMEDIAMODE_MIXED
A mixed session on the call. Mixed is one of the ISDN telematic services.
LINEMEDIAMODE_ADSI
An ADSI (Analog Display Services Interface) session on the call.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.
dwGenerateToneModes
The different kinds of tones that can be generated on this line. This member uses the following LINETONEMODE_ constants:
LINETONEMODE_CUSTOM
The tone is a custom tone defined by the specified frequencies.
LINETONEMODE_RINGBACK
The tone to be generated is a ringback tone.
LINETONEMODE_BUSY
The tone is a standard (station) busy tone.
LINETONEMODE_BEEP
The tone is a beep, as used to announce the beginning of a recording.
LINETONEMODE_BILLING
The tone is a billing information tone such as a credit card prompt tone.
dwGenerateToneMaxNumFreq
Contains the maximum number of frequencies that can be specified in describing a general tone using the LINEGENERATETONE data structure when generating a tone using lineGenerateTone. A value of 0 indicates that tone generation is not available.
dwGenerateDigitModes
Specifies the digit modes than can be generated on this line. This member uses the following LINEDIGITMODE_ constants:
LINEDIGITMODE_PULSE
Generate digits as pulse/rotary pulse sequences.
LINEDIGITMODE_DTMF
Generate digits as DTMF tones.
dwMonitorToneMaxNumFreq
Contains the maximum number of frequencies that can be specified in describing a general tone using the LINEMONITORTONE data structure when monitoring a general tone using lineMonitorTones. A value of 0 indicates that tone monitor is not available.
dwMonitorToneMaxNumEntries
Contains the maximum number of entries that can be specified in a tone list to lineMonitorTones.
dwMonitorDigitModes
Specifies the digit modes than can be detected on this line. This member uses the following LINEDIGITMODE_ constants:
LINEDIGITMODE_PULSE
Detect digits as audible clicks that are the result of rotary pulse sequences.
LINEDIGITMODE_DTMF
Detect digits as DTMF tones.
LINEDIGITMODE_DTMFEND
Detect the down edges of digits detected as DTMF tones.
dwGatherDigitsMinTimeout
dwGatherDigitsMaxTimeout
These members contain the minimum and maximum values in milliseconds that can be specified for both the first digit and inter-digit timeout values used by lineGatherDigits. If both these members are zero, timeouts are not supported.
dwMedCtlDigitMaxListSize
dwMedCtlMediaMaxListSize
dwMedCtlToneMaxListSize
dwMedCtlCallStateMaxListSize
These members contain the maximum number of entries that can be specified in the digit list, the media list, the tone list, and the call state list parameters of lineSetMediaControl respectively.
dwDevCapFlags
Specifies various Boolean device capabilities. This member uses the following LINEDEVCAPFLAGS_ constants:
LINEDEVCAPFLAGS_CROSSADDRCONF
Specifies whether calls on different addresses on this line can be conferenced.
LINEDEVCAPFLAGS_HIGHLEVCOMP
Specifies whether high-level compatibility information elements are supported on this line.
LINEDEVCAPFLAGS_LOWLEVCOMP
Specifies whether low-level compatibility information elements are supported on this line.
LINEDEVCAPFLAGS_MEDIACONTROL
Specifies whether media control operations are available for calls at this line.
LINEDEVCAPFLAGS_MULTIPLEADDR
Specifies whether lineMakeCall or lineDial are able to deal with multiple addresses at once (such as for inverse multiplexing).
LINEDEVCAPFLAGS_CLOSEDROP
Specifies what happens when an open line is closed while the application has calls active on the line. If TRUE, the service provider drops (clears) all active calls on the line when the last application that has opened the line closes it with lineClose. If FALSE, the service provider does not drop active calls in such cases. Instead, the calls remain active and under control of external device(s). A service provider typically sets this bit to FALSE if there is some other device that can keep the call alive. For example, if an analog line has the computer and phone set both connect directly to them in a party-line configuration, the offhook phone automatically keeps the call active even after the computer powers down.

Applications should check this flag to determine whether to warn the user (with an OK/Cancel dialog box) that active calls will be lost.

LINEDEVCAPFLAGS_DIALBILLING
LINEDEVCAPFLAGS_DIALQUIET
LINEDEVCAPFLAGS_DIALDIALTONE
These flags indicate whether the "$", "@", or "W" dialable string modifier is supported for a given line device. It is TRUE if the modifier is supported; otherwise, FALSE. The "?" (prompt user to continue dialing) is never supported by a line device. These flags allow an application to determine "up front" which modifiers would result in the generation of a LINEERR. The application has the choice of pre-scanning dialable strings for unsupported characters, or passing the "raw" string from lineTranslateAddress directly to the provider as part of lineMakeCall (lineDial, and so on) and let the function generate an error to tell it which unsupported modifier occurs first in the string.
dwMaxNumActiveCalls
Provides the maximum number of (minimum bandwidth) calls that can be active (connected) on the line at any one time. The actual number of active calls may be lower if higher bandwidth calls have been established on the line.
dwAnswerMode
Specifies the effect on the active call when answering another offering call on a line device. This member uses the following LINEANSWERMODE_ constants:
LINEANSWERMODE_NONE
Answering another call on the same line has no effect on the existing active call(s) on the line.
LINEANSWERMODE_DROP
The currently active call is automatically dropped.
LINEANSWERMODE_HOLD
The currently active call is automatically placed on hold.
dwRingModes
Contains the number of different ring modes that can be reported in the LINE_LINEDEVSTATE message with the ringing indication. Different ring modes range from one to dwRingModes. Zero indicates no ring.
dwLineStates
Specifies the different line status components for which the application may be notified in a LINE_LINEDEVSTATE message on this line. This member uses the following LINEDEVSTATE_ constants:
LINEDEVSTATE_OTHER
Device-status items other than those listed below have changed. The application should check the current device status to determine which items have changed.
LINEDEVSTATE_RINGING
The switch tells the line to alert the user. Service providers notify applications on each ring cycle by sending LINE_LINEDEVSTATE messages containing this constant. For example, in the United States, service providers send a message with this constant every six seconds.
LINEDEVSTATE_CONNECTED
The line was previously disconnected and is now connected to TAPI.
LINEDEVSTATE_DISCONNECTED
This line was previously connected and is now disconnected from TAPI.
LINEDEVSTATE_MSGWAITON
The "message waiting" indicator is turned on.
LINEDEVSTATE_MSGWAITOFF
The "message waiting" indicator is turned off.
LINEDEVSTATE_NUMCOMPLETIONS
The number of outstanding call completions on the line device has changed.
LINEDEVSTATE_INSERVICE
The line is connected to TAPI. This happens when TAPI is first activated or when the line wire is physically plugged in and in service at the switch while TAPI is active.
LINEDEVSTATE_OUTOFSERVICE
The line is out of service at the switch or physically disconnected. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_MAINTENANCE
Maintenance is being performed on the line at the switch. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_OPEN
The line has been opened.
LINEDEVSTATE_CLOSE
The line has been closed.
LINEDEVSTATE_NUMCALLS
The number of calls on the line device has changed.
LINEDEVSTATE_TERMINALS
The terminal settings have changed.
LINEDEVSTATE_ROAMMODE
The roam mode of the line device has changed.
LINEDEVSTATE_BATTERY
The battery level has changed significantly (cellular).
LINEDEVSTATE_SIGNAL
The signal level has changed significantly (cellular).
LINEDEVSTATE_DEVSPECIFIC
The line's device-specific information has changed.
LINEDEVSTATE_REINIT
Items have changed in the configuration of line devices. To become aware of these changes (such as for the appearance of new line devices), the application should reinitialize its use of TAPI. The hDevice parameter is left NULL for this state change as it applies to any of the lines in the system.
LINEDEVSTATE_LOCK
The locked status of the line device has changed.
LINEDEVSTATE_CAPSCHANGE
Indicates that due to configuration changes made by the user or other circumstances one or more of the members in the LINEDEVCAPS structure for the address have changed. The application should use lineGetDevCaps to read the updated structure. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI in order to obtain the updated information.
LINEDEVSTATE_CONFIGCHANGE
Indicates that configuration changes have been made to one or more of the media devices associated with the line device. The application, if it desires, may use lineGetDevConfig to read the updated information. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version do not receive any notification.
LINEDEVSTATE_TRANSLATECHANGE
Indicates that due to configuration changes made by the user or other circumstances one or more of the members in the LINETRANSLATECAPS structure have changed. The application should use lineGetTranslateCaps to read the updated structure. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI in order to obtain the updated information.
LINEDEVSTATE_COMPLCANCEL
Indicates that the call completion identified by the completion identifier contained in the dwParam2 parameter of the LINE_LINEDEVSTATE message has been externally canceled and is no longer considered valid (if that value were to be passed in a subsequent call to lineUncompleteCall, the function would fail with LINEERR_INVALCOMPLETIONID). If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version do not receive any notification.
LINEDEVSTATE_REMOVED
Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). Normally, a LINE_LINEDEVSTATE message with this value is immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version do not receive any notification.
dwUUIAcceptSize
Specifies the maximum size of user-user information that can be sent during a call accept.
dwUUIAnswerSize
Specifies the maximum size of user-user information that can be sent during a call answer.
dwUUIMakeCallSize
Specifies the maximum size of user-user information that can be sent during a make call.
dwUUIDropSize
Specifies the maximum size of user-user information that can be sent during a call drop.
dwUUISendUserUserInfoSize
Specifies the maximum size of user-user information that can be sent separately any time during a call with lineSendUserUserInfo.
dwUUICallInfoSize
Specifies the maximum size of user-user information that can be received in the LINECALLINFO structure.
MinDialParams
MaxDialParams
These members contain the minimum and maximum values in milliseconds for the dial parameters that can be set for calls on this line. Dialing parameters can be set to values in this range. The granularity of the actual settings is service provider-specific.
DefaultDialParams
Contains the default dial parameters used for calls on this line. These parameter values can be overridden on a per-call basis.
dwNumTerminals
The number of terminals that can be set for this line device, its addresses, or its calls. Individual terminals are referred to by terminal IDs and range from zero to one less than the value indicated by dwNumTerminals.
dwTerminalCapsSize
dwTerminalCapsOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device field containing an array with entries of type LINETERMCAPS. This array is indexed by terminal IDs, in the range from zero to dwNumTerminals minus one. Each entry in the array specifies the terminal device capabilities of the corresponding terminal.
dwTerminalTextEntrySize
The size in bytes of each of the terminal text descriptions pointed at by dwTerminalTextSize/Offset.
dwTerminalTextSize
dwTerminalTextOffset
The size in bytes of the variably sized field containing descriptive text about each of the line's available terminals, and the offset in bytes from the beginning of this data structure. Each message is dwTerminalTextEntrySize bytes long. The string format of these textual descriptions is indicated by dwStringFormat in the line's device capabilities.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes of the variably sized device-specific field, and the offset in bytes from the beginning of this data structure.
dwLineFeatures
Specifies the features available for this line using the LINEFEATURE_ constants. Invoking a supported feature requires the line to be in the proper state and the underlying line device to be opened in a compatible mode. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature may be available if the line is in the appropriate state for the operation to be meaningful. This member allows an application to discover which line features can be (and which can never be) supported by the device.
dwSettableDevStatus
The LINEDEVSTATUS_ values that can be modified using lineSetLineDevStatus.
dwDeviceClassesSize
dwDeviceClassesOffset
Length in bytes and offset from the beginning of LINEDEVCAPS of a string consisting of the device class identifiers supported on one or more addresses on this line for use with lineGetID, separated by NULLs; the last identifier in the list is followed by two NULLs.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

Older applications are compiled without new members in the LINEDEVCAPS structure, and using a SIZEOF LINEDEVCAPS smaller than the new size. The application passes in a dwAPIVersion parameter with the lineGetDevCaps function, which can be used for guidance by TAPI in handling this situation. If the application passes in a dwTotalSize member less than the size of the fixed portion of the structure as defined in the specified dwAPIVersion, LINEERR_STRUCTURETOOSMALL is returned. If sufficient memory has been allocated by the application, before calling TSPI_lineGetDevCaps, TAPI sets the dwNeededSize and dwUsedSize members to the fixed size of the structure as it existed in the specified API version.

New applications must be cognizant of the API version negotiated, and not examine the contents of members in the fixed portion beyond the original end of the fixed portion of the structure for the negotiated API version.

If the LINEBEARERMODE_DATA bit is set in the dwBearerModes member, the dwMaxRate member indicates the maximum rate of digital transmission on the bearer channel. The dwMaxRate member of the LINEDEVCAPS structure can contain valid values even if the dwBearerModes member of the LINEDEVCAPS structure is not set to LINEBEARERMODE_DATA.

If LINEBEARERMODE_DATA is not set in dwBearerModes, but the LINEBEARERMODE_VOICE value is set and the LINEMEDIAMODE_DATAMODEM value is set in the dwMediaModes member, the dwMaxRate member indicates the maximum SYNCHRONOUS (DCE) bit rate on the phone line for the attached modem or functional equivalent. For example, if the modem's fastest modulation speed is V.32bis at 14,400bps, dwMaxRate equals 14400. This is not the fastest DTE port rate (which would most likely be 38400, 57600, or 115200), but the fastest bit rate the modem supports on the phone line.

The application must be careful to check to see that LINEBEARERMODE_DATA is not set, to avoid misinterpreting the dwMaxRate member. It is likely to be 64000 or higher if LINEBEARERMODE_DATA is set.

It should also be noted that if the modem has not been specifically identified (for example, it is a "generic" modem), the figure indicated is a "best guess" based on examination of the modem.

The members dwSettableDevStatus through dwDeviceClassesOffset are available only to applications that open the line device with an API version of 2.0 or later.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINE_LINEDEVSTATE, LINECALLINFO, lineClose, lineDial, lineGatherDigits, LINEGENERATETONE, lineGenerateTone, lineGetDevCaps, lineGetID, lineGetTranslateCaps, lineSendUserUserInfo, lineMakeCall, LINEMONITORTONE, lineMonitorTones, lineSetMediaControl, LINETERMCAPS, lineTranslateAddress, LINETRANSLATECAPS, lineUncompleteCall


LINEDEVSTATUS

The LINEDEVSTATUS structure describes the current status of a line device.

typedef struct linedevstatus_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwNumOpens;
    DWORD  dwOpenMediaModes;
    DWORD  dwNumActiveCalls;
    DWORD  dwNumOnHoldCalls;
    DWORD  dwNumOnHoldPendCalls;
    DWORD  dwLineFeatures;
    DWORD  dwNumCallCompletions;
    DWORD  dwRingMode;
    DWORD  dwSignalLevel;
    DWORD  dwBatteryLevel;
    DWORD  dwRoamMode;

    DWORD  dwDevStatusFlags;

    DWORD  dwTerminalModesSize;
    DWORD  dwTerminalModesOffset;

    DWORD  dwDevSpecificSize;
    DWORD  dwDevSpecificOffset;

    DWORD dwAvailableMediaModes;
    DWORD dwAppInfoSize;
    DWORD dwAppInfoOffset;
} LINEDEVSTATUS, FAR *LPLINEDEVSTATUS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwNumOpens
The number of active opens on the line device.
dwOpenMediaModes
Bit array that indicates for which media modes the line device is currently open.
dwNumActiveCalls
The number of calls on the line in call states other than idle, onhold, onholdpendingtransfer, and onholdpendingconference.
dwNumOnHoldCalls
The number of calls on the line in the onhold state.
dwNumOnHoldPendingCalls
The number of calls on the line in the onholdpendingtransfer or onholdpendingconference state.
dwLineFeatures
Specifies the line-related API functions that are currently available on this line. This member uses the following LINEFEATURE_ constants:
LINEFEATURE_DEVSPECIFIC
Device-specific operations can be used on the line.
LINEFEATURE_DEVSPECIFICFEAT
Device-specific features can be used on the line.
LINEFEATURE_FORWARD
Forwarding of all addresses can be used on the line.
LINEFEATURE_MAKECALL
An outgoing call can be placed on this line using an unspecified address.
LINEFEATURE_SETMEDIACONTROL
Media control can be set on this line.
LINEFEATURE_SETTERMINAL
Terminal modes for this line can be set.
dwNumCallCompletions
The number of outstanding call completion requests on the line.
dwRingMode
The current ring mode on the line device.
dwSignalLevel
The current signal level of the connection on the line. This is a value in the range 0x00000000 (weakest signal) to 0x0000FFFF (strongest signal).
dwBatteryLevel
The current battery level of the line device hardware. This is a value in the range 0x00000000 (battery empty) to 0x0000FFFF (battery full).
dwRoamMode
The current roam mode of the line device. This member uses the following LINEROAMMODE_ constants:
LINEROAMMODE_UNKNOWN
The roam mode is currently unknown but may become known later.
LINEROAMMODE_UNAVAIL
The roam mode is unavailable and cannot be known.
LINEROAMMODE_HOME
The line is connected to the home network node.
LINEROAMMODE_ROAMA
The line is connected to the Roam-A carrier and calls are charged accordingly.
LINEROAMMODE_ROAMB
The line is connected to the Roam-B carrier and calls are charged accordingly.
dwDevStatusFlags
The size in bytes of this data structure that contains useful information, of type LINEDEVSTATUSFLAGS_.
LINEDEVSTATUSFLAGS_CONNECTED
Specifies whether the line is connected to TAPI. If TRUE, the line is connected and API is able to operate on the line device. If FALSE, the line is disconnected and the application is unable to control the line device using TAPI.
LINEDEVSTATUSFLAGS_LOCKED
This bit is most often used with line devices associated with cellular phones. Many cellular phones have a security mechanism that requires the entry of a password to enable the phone to place calls. This bit may be used to indicate to applications that the phone is locked and cannot place calls until the password is entered on the user interface of the phone, so that the application can present an appropriate alert to the user.
LINEDEVSTATUSFLAGS_MSGWAIT
This member indicates whether the line has a message waiting. If TRUE, a message is waiting; if FALSE, no message is waiting.
LINEDEVSTATUSFLAGS_INSERVICE
This member indicates whether the line is in service. If TRUE, the line is in service; if FALSE, the line is out of service.
dwTerminalModesSize
dwTerminalModesOffset
The size in bytes of the variably sized device field containing an array with DWORD-sized entries, and the offset in bytes from the beginning of this data structure. This array is indexed by terminal IDs, in the range from zero to dwNumTerminals minus one. Each entry in the array specifies the current terminal modes for the corresponding terminal set using the lineSetTerminal function for this line. This member uses the following LINETERMMODE_ constants:
LINETERMMODE_LAMPS
Lamp events sent from the line to the terminal.
LINETERMMODE_BUTTONS
Button-press events sent from the terminal to the line.
LINETERMMODE_DISPLAY
Display information sent from the line to the terminal.
LINETERMMODE_RINGER
Ringer-control information sent from the switch to the terminal.
LINETERMMODE_HOOKSWITCH
Hookswitch events sent between the terminal and the line.
LINETERMMODE_MEDIATOLINE
The unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIAFROMTERM
The unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIABIDIRECT
The bidirectional media stream associated with a call on the line and the terminal. Use this value when the routing of both unidirectional channels of a call's media stream cannot be controlled independently.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes of the variably sized device-specific field, and the offset in bytes from the beginning of this data structure.
dwAvailableMediaModes
Indicates the media modes that can be invoked on new calls created on this line device, when the dwLineFeatures member indicates that new calls are possible. If this member is zero, it indicates that the service provider either does not know or cannot indicate which media modes are available, in which case any or all of the media modes indicated in the dwMediaModes member in LINEDEVCAPS may be available.
dwAppInfoSize
dwAppInfoOffset
Length in bytes and offset from the beginning of LINEDEVSTATUS of an array of LINEAPPINFO structures. The dwNumOpens member indicates the number of elements in the array. Each element in the array identifies an application that has the line open.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

The members dwAvailableMediaModes through dwAppInfoOffset are available only to applications that open the line device with an API version of 2.0 or later.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINEAPPINFO, LINEDEVCAPS, lineSetTerminal


LINEDIALPARAMS

The LINEDIALPARAMS structure specifies a collection of dialing-related fields.

typedef struct linedialparams_tag {
    DWORD  dwDialPause;
    DWORD  dwDialSpeed;
    DWORD  dwDigitDuration;
    DWORD  dwWaitForDialtone;
} LINEDIALPARAMS, FAR *LPLINEDIALPARAMS;

Members

dwDialPause
The duration in milliseconds of a comma in the dialable address.
dwDialSpeed
The interdigit time period in milliseconds between successive digits.
dwDigitDuration
The duration in milliseconds of a digit.
dwWaitForDialtone
The maximum amount of time that should be waited for dial tone when a 'W' is used in the dialable address.

Remarks

No extensions.

When a value of 0 is specified for a field, the default value for that field is used. If a nonzero value is specified for a field that is outside the range specified by the corresponding fields in MinDialParams and MaxDialParams in the LINEDEVCAPS structure, the nearest value within the valid range is used instead.

The lineMakeCall function allows an application to adjust the dialing parameters to be used for the call. The lineSetCallParams function can be used to adjust the dialing parameters of an existing call. The LINECALLINFO structure lists the call's current dialing parameters.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINECALLINFO, LINEDEVCAPS, lineMakeCall, lineSetCallParams


LINEEXTENSIONID

The LINEEXTENSIONID structure describes an extension identifier. Extension IDs are used to identify service provider-specific extensions for line devices.

typedef struct lineextensionid_tag {
    DWORD  dwExtensionID0;
    DWORD  dwExtensionID1;
    DWORD  dwExtensionID2;
    DWORD  dwExtensionID3;
} LINEEXTENSIONID, FAR *LPLINEEXTENSIONID;

Members

dwExtensionID0
dwExtensionID1
dwExtensionID2
dwExtensionID3
These four DWORD-sized members together specify a universally unique extension identifier that identifies a line device class extension.

Remarks

No extensions.

Extension identifiers are generated using an SDK-provided generation utility.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.


LINEFORWARD

The LINEFORWARD structure describes an entry of the forwarding instructions.

typedef struct lineforward_tag {
    DWORD  dwForwardMode;

    DWORD  dwCallerAddressSize;
    DWORD  dwCallerAddressOffset;

    DWORD  dwDestCountryCode;
    DWORD  dwDestAddressSize;
    DWORD  dwDestAddressOffset;
} LINEFORWARD, FAR *LPLINEFORWARD;

Members

dwForwardMode
The types of forwarding. The dwForwardMode member can have only a single bit set. This member uses the following LINEFORWARDMODE_ constants:
LINEFORWARDMODE_UNCOND
Forward all calls unconditionally, irrespective of their origin. Use this value when unconditional forwarding for internal and external calls cannot be controlled separately. Unconditional forwarding overrides forwarding on busy and/or no-answer conditions.
LINEFORWARDMODE_UNCONDINTERNAL
Forward all internal calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.
LINEFORWARDMODE_UNCONDEXTERNAL
Forward all external calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.
LINEFORWARDMODE_UNCONDSPECIFIC
Unconditionally forward all calls that originated at a specified address (selective call forwarding).
LINEFORWARDMODE_BUSY
Forward all calls on busy, irrespective of their origin. Use this value when forwarding for internal and external calls both on busy and on no answer cannot be controlled separately.
LINEFORWARDMODE_BUSYINTERNAL
Forward all internal calls on busy. Use this value when forwarding for internal and external calls on busy and on no answer can be controlled separately.
LINEFORWARDMODE_BUSYEXTERNAL
Forward all external calls on busy. Use this value when forwarding for internal and external calls on busy and on no answer can be controlled separately.
LINEFORWARDMODE_BUSYSPECIFIC
Forward on busy all calls that originated at a specified address (selective call forwarding).
LINEFORWARDMODE_NOANSW
Forward all calls on no answer, irrespective of their origin. Use this value when call forwarding for internal and external calls on no answer cannot be controlled separately.
LINEFORWARDMODE_NOANSWINTERNAL
Forward all internal calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.
LINEFORWARDMODE_NOANSWEXTERNAL
Forward all external calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.
LINEFORWARDMODE_NOANSWSPECIFIC
Forward all calls that originated at a specified address on no answer (selective call forwarding).
LINEFORWARDMODE_BUSYNA
Forward all calls on busy/no answer, irrespective of their origin. Use this value when forwarding for internal and external calls on both busy and on no answer cannot be controlled separately.
LINEFORWARDMODE_BUSYNAINTERNAL
Forward all internal calls on busy/no answer. Use this value when call forwarding on busy and on no answer cannot be controlled separately for internal calls.
LINEFORWARDMODE_BUSYNAEXTERNAL
Forward all external calls on busy/no answer. Use this value when call forwarding on busy and on no answer cannot be controlled separately for internal calls.
LINEFORWARDMODE_BUSYNASPECIFIC
Forward on busy/no answer all calls that originated at a specified address (selective call forwarding).
LINEFORWARDMODE_UNKNOWN
Calls are forwarded, but the conditions under which forwarding occurs are not known at this time. It is possible that the conditions may become known at a future time.
LINEFORWARDMODE_UNAVAIL
Calls are forwarded, but the conditions under which forwarding occurs are not known, and are never known by the service provider.
dwCallerAddressSize
dwCallerAddressOffset
The size in bytes of the variably sized address field containing the address of a caller to be forwarded, and the offset in bytes from the beginning of the containing data structure. The dwCallerAddressSize/Offset member is set to zero if dwForwardMode is not one of the following: LINEFORWARDMODE_BUSYNASPECIFIC, LINEFORWARDMODE_NOANSWSPECIFIC, LINEFORWARDMODE_UNCONDSPECIFIC, or LINEFORWARDMODE_BUSYSPECIFIC.
dwDestCountryCode
The country code of the destination address to which the call is to be forwarded.
dwDestAddressSize
dwDestAddressOffset
The size in bytes of the variably sized address field containing the address of the address where calls are to be forwarded, and the offset in bytes from the beginning of the containing data structure.

Remarks

No extensions.

Each entry in the LINEFORWARD structure specifies a forwarding request.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.


LINEFORWARDLIST

The LINEFORWARDLIST structure describes a list of forwarding instructions.

typedef struct lineforwardlist_tag {
    DWORD  dwTotalSize;

    DWORD  dwNumEntries;
    LINEFORWARD  ForwardList[1];
} LINEFORWARDLIST, FAR *LPLINEFORWARDLIST;

Members

dwTotalSize
The total size in bytes of the data structure.
dwNumEntries
Number of entries in the array specified as ForwardList[ ].
ForwardList[ ]
An array of forwarding instruction. The array's entries are of type LINEFORWARD.

Remarks

No extensions.

The LINEFORWARDLIST structure defines the forwarding parameters requested for forwarding calls on an address or on all addresses on a line.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.


LINEGENERATETONE

The LINEGENERATETONE structure contains information about a tone to be generated.

typedef struct linegeneratetone_tag {
    DWORD  dwFrequency;
    DWORD  dwCadenceOn;
    DWORD  dwCadenceOff;
    DWORD  dwVolume;
} LINEGENERATETONE, FAR *LPLINEGENERATETONE;

Members

dwFrequency
The frequency in hertz of this tone component. A service provider may adjust (round up or down) the frequency specified by the application to fit its resolution.
dwCadenceOn
The "on" duration in milliseconds of the cadence of the custom tone to be generated. Zero means no tone is generated.
dwCadenceOff
The "off" duration in milliseconds of the cadence of the custom tone to be generated. Zero means no off time, that is, a constant tone.
dwVolume
The volume level at which the tone is to be generated. A value of 0x0000FFFF represents full volume, and a value of 0x00000000 is silence.

Remarks

No extensions.

This structure is only used for the generation of tones. It is not used for tone monitoring.


LINEINITIALIZEEXPARAMS

typedef struct lineinitializeexparams_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;
    DWORD  dwOptions;

  union
  {
    HANDLE  hEvent;
    HANDLE  hCompletionPort;
  } Handles;

    DWORD  dwCompletionKey;

} LINEINITIALIZEEXPARAMS, FAR *LPLINEINITIALIZEEXPARAMS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwOptions
One of the LINEINITIALIZEEXOPTION_ constants. Specifies the event notification mechanism the application desires to use.
hEvent
If dwOptions specifies LINEINITIALIZEEXOPTION_USEEVENT, TAPI returns the event handle in this field.
hCompletionPort
If dwOptions specifies LINEINITIALIZEEXOPTION_USECOMPLETIONPORT, the application must specify in this field the handle of an existing completion port opened using CreateIoCompletionPort.
dwCompletionKey
If dwOptions specifies LINEINITIALIZEEXOPTION_USECOMPLETIONPORT, the application must specify in this field a value that is returned through the lpCompletionKey parameter of GetQueuedCompletionStatus to identify the completion message as a telephony message.

Remarks

See lineInitializeEx for further information on these options.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.


LINELOCATIONENTRY

The LINELOCATIONENTRY structure describes a location used to provide an address translation context.

typedef struct linelocationentry_tag {
    DWORD  dwPermanentLocationID;
    DWORD  dwLocationNameSize;
    DWORD  dwLocationNameOffset;
    DWORD  dwCountryCode;
    DWORD  dwCityCodeSize;
    DWORD  dwCityCodeOffset;
    DWORD  dwPreferredCardID;
    DWORD  dwLocalAccessCodeSize;
    DWORD  dwLocalAccessCodeOffset;
    DWORD  dwLongDistanceAccessCodeSize;
    DWORD  dwLongDistanceAccessCodeOffset;
    DWORD  dwTollPrefixListSize;
    DWORD  dwTollPrefixListOffset;
    DWORD  dwCountryID;
    DWORD  dwOptions;
    DWORD  dwCancelCallWaitingSize;
    DWORD  dwCancelCallWaitingOffset;
} LINELOCATIONENTRY, FAR *LPLINELOCATIONENTRY;

Members

dwPermanentLocationID
The permanent identifier that identifies the location.
dwLocationNameSize
dwLocationNameOffset
Contains a NULL-terminated ASCII string (size includes the NULL) that describes the location in a user-friendly manner.
dwCountryCode
The country code of the location.
dwPreferredCardID
The preferred calling card when dialing from this location.
dwCityCodeSize
dwCityCodeOffset
Contains a NULL-terminated ASCII string specifying the city/area code associated with the location (the size includes the NULL). This information, along with the country code, can be used by applications to "default" entry fields for the user when entering phone numbers, to encourage the entry of proper canonical numbers.
dwLocalAccessCodeSize
dwLocalAccessCodeOffset
The size in bytes and the offset in bytes from the beginning of the LINETRANSLATECAPS structure of a NULL-terminated ASCII string containing the access code to be dialed before calls to addresses in the local calling area.
dwLongDistanceAccessCodeSize
dwLongDistanceAccessCodeOffset
The size in bytes and the offset in bytes from the beginning of the LINETRANSLATECAPS structure of a NULL-terminated ASCII string containing the access code to be dialed before calls to addresses outside the local calling area.
dwTollPrefixListSize
dwTollPrefixListOffset
The size in bytes and the offset in bytes from the beginning of the LINETRANSLATECAPS structure of a NULL-terminated ASCII string containing the toll prefix list for the location. The string contains only prefixes consisting of the digits "0" through "9", separated from each other by a single "," (comma) character.
dwCountryID
The country identifier of the country selected for the location. This can be used with the lineGetCountry function to obtain additional information about the specific country, such as the country name (the dwCountryCode member cannot be used for this purpose because country codes are not unique).
dwOptions
Indicates options in effect for this location, with values taken from the LINELOCATIONOPTION_ set of constants.
dwCancelCallWaitingSize
dwCancelCallWaitingOffset
The size in bytes and the offset in bytes from the beginning of the LINETRANSLATECAPS structure of a NULL-terminated ASCII string containing the dial digits and modifier characters that should be prefixed to the dialable string (after the pulse/tone character) when an application sets the LINETRANSLATEOPTION_CANCELCALLWAITING bit in the dwTranslateOptions parameter of lineTranslateAddress. If no prefix is defined, this may be indicated by dwCancelCallWaitingSize being set to zero, or by it being set to 1 and dwCancelCallWaitingOffset pointing to an empty string (single NULL byte).

Remarks

No extensions.

Older applications are compiled without knowledge of these new fields, and using a SIZEOF LINELOCATIONENTRY smaller than the new size. Because this is an array in the variable portion of a LINETRANSLATECAPS structure, it is imperative that older applications receive LINELOCATIONENTRY structures in the format they previously expected, or they are not able to index through the array properly. The application passes in a dwAPIVersion parameter with the lineGetTranslateCaps function, which can be used for guidance by TAPI in handling this situation. The lineGetTranslateCaps function should use the LINELOCATIONENTRY members and size that match the indicated API version, when building the LINETRANSLATECAPS structure to be returned to the application.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

lineGetCountry, lineGetTranslateCaps, lineTranslateAddress, LINETRANSLATECAPS


LINEMEDIACONTROLCALLSTATE

The LINEMEDIACONTROLCALLSTATE structure describes a media action to be executed when detecting transitions into one or more call states.

typedef struct linemediacontrolcallstate_tag {
    DWORD  dwCallStates;
    DWORD  dwMediaControl;
} LINEMEDIACONTROLCALLSTATE, FAR *LPLINEMEDIACONTROLCALLSTATE;

Members

dwCallStates
Specifies one or more call states. This member uses the following LINECALLSTATE_ constants:
LINECALLSTATE_IDLE
The call is idle—no call exists.
LINECALLSTATE_OFFERING
The call is being offered to the station, signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user. Alerting is done by the switch instructing the line to ring, and it does not affect any call states.
LINECALLSTATE_ACCEPTED
The call was offering and has been accepted. This indicates to other (monitoring) applications that the current owner application has claimed responsibility for answering the call. In ISDN, this also initiates alerting to both parties.
LINECALLSTATE_DIALTONE
The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number.
LINECALLSTATE_DIALING
Destination address information (a phone number) is being sent to the switch over the call. The function lineGenerateDigits does not place the line into the dialing state.
LINECALLSTATE_RINGBACK
The call is receiving ringback from the called address. Ringback indicates that the other station has been reached and is being alerted.
LINECALLSTATE_BUSY
The call is receiving a busy tone. Busy tone indicates that the call cannot be completed because either a circuit (trunk) or the remote party's station are in use.
LINECALLSTATE_SPECIALINFO
Special information is sent by the network. Special information is typically sent when the destination cannot be reached.
LINECALLSTATE_CONNECTED
The call has been established, and the connection is made. Information is able to flow over the call between the originating address and the destination address.
LINECALLSTATE_PROCEEDING
Dialing has completed and the call is proceeding through the switch or telephone network.
LINECALLSTATE_ONHOLD
The call is on hold by the switch.
LINECALLSTATE_CONFERENCED
The call is currently a member of a multiparty conference call.
LINECALLSTATE_ONHOLDPENDCONF
The call is currently on hold while it is being added to a conference.
LINECALLSTATE_ONHOLDPENDTRANSF
The call is currently on hold awaiting transfer to another number.
LINECALLSTATE_DISCONNECTED
The remote party has disconnected from the call.
LINECALLSTATE_UNKNOWN
The state of the call is not known. This may be due to limitations of the call-progress detection implementation.
dwMediaControl
The media control action. This member uses the following LINEMEDIACONTROL_ constants:
LINEMEDIACONTROL_NONE
No change is to be made to the media stream.
LINEMEDIACONTROL_RESET
Reset the media stream. Equivalent to an end-of-input. All buffers are released.
LINEMEDIACONTROL_PAUSE
Temporarily pause the media stream.
LINEMEDIACONTROL_RESUME
Start or resume a paused media stream.
LINEMEDIACONTROL_RATEUP
The speed of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_RATEDOWN
The speed of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_RATENORMAL
The speed of the media stream is returned to normal.
LINEMEDIACONTROL_VOLUMEUP
The amplitude of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMEDOWN
The amplitude of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMENORMAL
The amplitude of the media stream is returned to normal.

Remarks

No extensions.

The LINEMEDIACONTROLCALLSTATE structure defines a triple <call state(s), media-control action>. An array of these triples is passed to the lineSetMediaControl function to set the media control actions triggered by the transition to the call state of the given call. When a transition to a listed call state is detected, the corresponding action on the media stream is invoked.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

lineGenerateDigits, lineSetMediaControl


LINEMEDIACONTROLDIGIT

The LINEMEDIACONTROLDIGIT structure describes a media action to be executed when detecting a digit. It is used as an entry in an array.

typedef struct linemediacontroldigit_tag {
    DWORD  dwDigit;
    DWORD  dwDigitModes;
    DWORD  dwMediaControl;
} LINEMEDIACONTROLDIGIT, FAR *LPLINEMEDIACONTROLDIGIT;

Members

dwDigit
The low-order byte of this DWORD specifies the digit in ASCII whose detection is to trigger a media action. Valid digits depend on the media mode.
dwDigitModes
The digit mode(s) that are to be monitored. This member uses the following LINEDIGITMODE_ constants:
LINEDIGITMODE_PULSE
Detect digits as audible clicks that are the result of rotary pulse sequences. Valid digits for pulse are '0' through '9'.
LINEDIGITMODE_DTMF
Detect digits as DTMF tones. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.
LINEDIGITMODE_DTMFEND
Detect and provide application notification of DTMF down edges. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.
dwMediaControl
The media control action. This member uses the following LINEMEDIACONTROL_ constants:
LINEMEDIACONTROL_NONE
No change is to be made to the media stream.
LINEMEDIACONTROL_RESET
Reset the media stream. Equivalent to an end-of-input. All buffers are released.
LINEMEDIACONTROL_PAUSE
Temporarily pause the media stream.
LINEMEDIACONTROL_RESUME
Start or resume a paused media stream.
LINEMEDIACONTROL_RATEUP
The speed of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_RATEDOWN
The speed of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_RATENORMAL
The speed of the media stream is returned to normal.
LINEMEDIACONTROL_VOLUMEUP
The amplitude of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMEDOWN
The amplitude of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMENORMAL
The amplitude of the media stream is returned to normal.

Remarks

No extensions.

The LINEMEDIACONTROLMEDIA structure defines a triple <digit, digit mode(s), media-control action>. An array of these triples is passed to the lineSetMediaControl function to set the media control actions triggered by digits detected on a given call. When a listed digit is detected, then the corresponding action on the media stream is invoked.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINEMEDIACONTROLMEDIA, lineSetMediaControl


LINEMEDIACONTROLMEDIA

The LINEMEDIACONTROLMEDIA structure describes a media action to be executed when detecting a media mode change. It is used as an entry in an array.

typedef struct linemediacontrolmedia_tag {
    DWORD  dwMediaModes;
    DWORD  dwDuration;
    DWORD  dwMediaControl;
} LINEMEDIACONTROLMEDIA, FAR *LPLINEMEDIACONTROLMEDIA;

Members

dwMediaModes
One or more media modes. This member uses the following LINEMEDIAMODE_ constants:
LINEMEDIAMODE_UNKNOWN
A media stream exists but its mode is not known. This would correspond to a call with an unclassified media type. In typical analog telephony environments, an incoming call's media mode may be unknown until after the call has been answered and the media stream filtered to make a determination.
LINEMEDIAMODE_INTERACTIVEVOICE
The presence of voice energy on the call and the call is treated as an interactive call with humans on both ends.
LINEMEDIAMODE_AUTOMATEDVOICE
The presence of voice energy on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM
A data modem session on the call.
LINEMEDIAMODE_G3FAX
A group 3 fax is being sent or received over the call.
LINEMEDIAMODE_G4FAX
A group 4 fax is being sent or received over the call.
LINEMEDIAMODE_TDD
A TDD (Telephony Devices for the Deaf) session on the call.
LINEMEDIAMODE_DIGITALDATA
Digital data is being sent or received over the call.
LINEMEDIAMODE_TELETEX
A teletex session on the call. Teletex is one of the telematic services.
LINEMEDIAMODE_VIDEOTEX
A videotex session on the call. Videotex is one of the telematic services.
LINEMEDIAMODE_TELEX
A telex session on the call. Telex is one of the telematic services.
LINEMEDIAMODE_MIXED
A mixed session on the call. Mixed is one of the ISDN telematic services.
LINEMEDIAMODE_ADSI
An ADSI (Analog Display Services Interface) session on the call.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.
dwDuration
The duration in milliseconds during which the media mode should be present before the application should be notified or media control action should be taken.
dwMediaControl
The media control action. This member uses the following LINEMEDIACONTROL_ constants:
LINEMEDIACONTROL_NONE
No change is to be made to the media stream.
LINEMEDIACONTROL_RESET
Reset the media stream. Equivalent to an end-of-input. All buffers are released.
LINEMEDIACONTROL_PAUSE
Temporarily pause the media stream.
LINEMEDIACONTROL_RESUME
Start or resume a paused media stream.
LINEMEDIACONTROL_RATEUP
The speed of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_RATEDOWN
The speed of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_RATENORMAL
The speed of the media stream is returned to normal.
LINEMEDIACONTROL_VOLUMEUP
The amplitude of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMEDOWN
The amplitude of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMENORMAL
The amplitude of the media stream is returned to normal.

Remarks

No extensions.

The LINEMEDIACONTROLMEDIA structure defines a triple <media mode(s), duration, media-control action>. An array of these triples is passed to the lineSetMediaControl function to set the media control actions triggered by media mode changes for a given call. When a change to a listed media mode is detected, then the corresponding action on the media stream is invoked.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

lineSetMediaControl


LINEMEDIACONTROLTONE

The LINEMEDIACONTROLTONE structure describes a media action to be executed when a tone has been detected. It is used as an entry in an array.

typedef struct linemediacontroltone_tag {
    DWORD  dwAppSpecific;
    DWORD  dwDuration;
    DWORD  dwFrequency1;
    DWORD  dwFrequency2;
    DWORD  dwFrequency3;
    DWORD  dwMediaControl;
} LINEMEDIACONTROLTONE, FAR *LPLINEMEDIACONTROLTONE;

Members

dwAppSpecific
Used by the application for tagging the tone. When this tone is detected, the value of the dwAppSpecific member is passed back to the application.
dwDuration
The duration in milliseconds during which the tone should be present before a detection is made.
dwFrequency1
dwFrequency2
dwFrequency3
The frequency in hertz of a component of the tone. If fewer than three frequencies are needed in the tone, a value of 0 should be used for the unused frequencies. A tone with all three frequencies set to zero is interpreted as silence and can be use for silence detection.
dwMediaControl
The media control action. This member uses the following LINEMEDIACONTROL_ constants:
LINEMEDIACONTROL_NONE
No change is to be made to the media stream.
LINEMEDIACONTROL_RESET
Reset the media stream. Equivalent to an end-of-input. All buffers are released.
LINEMEDIACONTROL_PAUSE
Temporarily pause the media stream.
LINEMEDIACONTROL_RESUME
Start or resume a paused media stream.
LINEMEDIACONTROL_RATEUP
The speed of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_RATEDOWN
The speed of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_RATENORMAL
The speed of the media stream is returned to normal.
LINEMEDIACONTROL_VOLUMEUP
The amplitude of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMEDOWN
The amplitude of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMENORMAL
The amplitude of the media stream is returned to normal.

Remarks

No extensions.

The LINEMEDIACONTROLTONE structure defines a tuple <tone, media-control action>. An array of these tuples is passed to the lineSetMediaControl function to set media control actions triggered by media mode changes for a given call. When a change to a listed media mode is detected, the corresponding action on the media stream is invoked.

A tone with all frequencies set to zero corresponds to silence. An application can thus monitor the call's information stream for silence.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

lineSetMediaControl


LINEMESSAGE

typedef struct linemessage_tag {
    DWORD  hDevice;
    DWORD  dwMessageID;
    DWORD  dwCallbackInstance;
    DWORD  dwParam1;
    DWORD  dwParam2;
    DWORD  dwParam3;
} LINEMESSAGE, FAR *LPLINEMESSAGE;

Members

hDevice
A handle to either a line device or a call. The nature of this handle (line handle or call handle) can be determined by the context provided by dwMessageID.
dwMessageID
A line or call device message.
dwCallbackInstance
Instance data passed back to the application, which was specified by the application in lineInitializeEx. This DWORD is not interpreted by TAPI.
dwParam1
A parameter for the message.
dwParam2
A parameter for the message.
dwParam3
A parameter for the message.

Remarks

For information about parameter values passed in this structure, see Line Device Messages.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.


LINEMONITORTONE

The LINEMONITORTONE structure describes a tone to be monitored. This is used as an entry in an array.

typedef struct linemonitortone_tag {
    DWORD  dwAppSpecific;
    DWORD  dwDuration;
    DWORD  dwFrequency1;
    DWORD  dwFrequency2;
    DWORD  dwFrequency3;
} LINEMONITORTONE, FAR *LPLINEMONITORTONE;

Members

dwAppSpecific
Used by the application for tagging the tone. When this tone is detected, the value of the dwAppSpecific member is passed back to the application.
dwDuration
The duration in milliseconds during which the tone should be present before a detection is made.
dwFrequency1
dwFrequency2
dwFrequency3
The frequency in hertz of a component of the tone. If fewer than three frequencies are needed in the tone, a value of 0 should be used for the unused frequencies. A tone with all three frequencies set to zero is interpreted as silence and can be used for silence detection.

Remarks

No extensions.

The LINEMONITORTONE structure defines a tone for the purpose of detection. An array of tones is passed to the lineMonitorTones function which monitors these tones and sends a LINE_MONITORTONE message to the application when a detection is made.

A tone with all frequencies set to zero corresponds to silence. An application can thus monitor the call's information stream for silence.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINE_MONITORTONE, lineMonitorTones


LINEPROVIDERENTRY

The LINEPROVIDERENTRY structure provides the information for a single service provider entry. An array of these structures is returned as part of the LINEPROVIDERLIST structure returned by the function lineGetProviderList.

typedef struct lineproviderentry_tag {
    DWORD  dwPermanentProviderID;
    DWORD  dwProviderFilenameSize;
    DWORD  dwProviderFilenameOffset;
} LINEPROVIDERENTRY, FAR *LPLINEPROVIDERENTRY;

Members

dwPermanentProviderID
The permanent provider identifier of the entry.
dwProviderFilenameSize
dwProviderFilenameOffset
The size in bytes and the offset in bytes from the beginning of the LINEPROVIDERLIST structure of a NULL-terminated ASCII string containing the filename (path) of the service provider DLL (.TSP) file.

Remarks

Not extensible.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

lineGetProviderList, LINEPROVIDERLIST


LINEPROVIDERLIST

The LINEPROVIDERLIST structure describes a list of service providers. A structure of this type is returned by the lineGetProviderList function.

typedef struct lineproviderlist_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwNumProviders;
    DWORD  dwProviderListSize;
    DWORD  dwProviderListOffset;
} LINEPROVIDERLIST, FAR *LPLINEPROVIDERLIST;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwNumProviders
The number of LINEPROVIDERENTRY structures present in the array denominated by dwProviderListSize and dwProviderListOffset.
dwProviderListSize
dwProviderListOffset
The size in bytes and the offset in bytes from the beginning of this data structure of an array of LINEPROVIDERENTRY elements, which provide the information on each service provider.

Remarks

Not extensible.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.


LINEPROXYREQUEST

typedef struct lineproxyrequest_tag {
    DWORD dwSize;
    DWORD dwClientMachineNameSize;
    DWORD dwClientMachineNameOffset;
    DWORD dwClientUserNameSize;
    DWORD dwClientUserNameOffset;
    DWORD dwClientAppAPIVersion;
    DWORD dwRequestType;
  union {
   struct {
    DWORD dwAddressID;
      LINEAGENTGROUPLIST GroupList;
      } SetAgentGroup;
   struct {
    DWORD dwAddressID;
    DWORD dwAgentState;
    DWORD dwNextAgentState;
      } SetAgentState;
   struct {
    DWORD dwAddressID;
    DWORD dwActivityID;
      } SetAgentActivity;
   struct {
    DWORD dwAddressID;
      LINEAGENTCAPS AgentCaps;
      } GetAgentCaps;
   struct {
    DWORD dwAddressID;
      LINEAGENTSTATUS AgentStatus;
      } GetAgentStatus;
   struct {
    DWORD dwAddressID;
    DWORD dwAgentExtensionIDIndex;
    DWORD dwSize;
      BYTE Params[1];
      } AgentSpecific;
   struct {
    DWORD dwAddressID;
      LINEAGENTACTIVITYLIST ActivityList;
      } GetAgentActivityList;
   struct {
    DWORD dwAddressID;
      LINEAGENTGROUPLIST GroupList;
      } GetAgentGroupList;
  };
} LINEPROXYREQUEST, FAR *LPLINEPROXYREQUEST;

Members

dwSize
The total number of bytes allocated by TAPI to contain the LINEPROXYREQUEST structure. The dwTotalSize member of any structure contained within LINEPROXYREQUEST (for example, LINEAGENTCAPS) reflects only the number of bytes allocated for that specific structure.
dwClientMachineNameSize
dwClientMachineNameOffset
Size in bytes (including the terminating NULL) and offset from the beginning of LINEPROXYREQUEST of a NULL-terminated string identifying the client machine that made this request.
dwClientUserNameSize
dwClientUserNameOffset
Size in bytes (including the terminating NULL) and offset from the beginning of LINEPROXYREQUEST of a NULL-terminated string identifying the user under whose account the application is running on the client machine.
dwClientAppAPIVersion
The global (highest) API version supported by the application that made the request. The proxy handler should restrict the contents of any data returned to the application to those members and values that were defined in this, or earlier, versions of TAPI.
dwRequestType
One of the LINEPROXYREQUEST_ constants. Identifies the type of function and the union component that defines the remaining data in the structure.
SetAgentGroup
The union component used when dwRequestType is LINEPROXYREQUEST_SETAGENT.
dwAddressID
The identifier of the address for which the agent is to be set.
GroupList
A structure of type LINEAGENTGROUPLIST. Offsets within this structure are relative to the beginning of SetAgentGroup.GroupList rather than to the beginning of the LINEPROXYREQUEST structure.
SetAgentState
The union component used when dwRequestType is LINEPROXYREQUEST_SETAGENTSTATE.
dwAddressID
The identifier of the address for which the agent state is to be set.
dwAgentState
The new agent state, or zero to leave the agent state unchanged.
dwNextAgentState
The new next agent state, or zero to use the default next state associated with the specified agent state.
SetAgentActivity
The union component used when dwRequestType is LINEPROXYREQUEST_SETAGENTACTIVITY.
dwAddressID
The identifier of the address for which the agent activity is to be set.
dwActivityID
The identifier for the activity being selected.
GetAgentCaps
The union component used when dwRequestType is LINEPROXYREQUEST_GETAGENTCAPS.
dwAddressID
The identifier of the address for which the agent capabilities are to be retrieved.
AgentCaps
A structure of type LINEAGENTCAPS. Offsets within this structure are relative to the beginning of GetAgentCaps.AgentCaps rather than to the beginning of the LINEPROXYREQUEST structure. The dwTotalSize member is set by TAPI and the remaining bytes set to zero. The proxy handler must fill in dwNeededSize, dwUsedSize, and the remaining members as appropriate, before calling lineProxyResponse.
GetAgentStatus
The union component used when dwRequestType is LINEPROXYREQUEST_SETAGENTGROUP.
dwAddressID
The identifier of the address for which the agent status is to be retrieved.
AgentStatus
A structure of type LINEAGENTSTATUS. Offsets within this structure are relative to the beginning of GetAgentStatus.AgentStatus rather than to the beginning of the LINEPROXYREQUEST structure. The dwTotalSize member is set by TAPI and the remaining bytes set to zero. The proxy handler must fill in dwNeededSize, dwUsedSize, and the remaining members as appropriate, before calling lineProxyResponse.
AgentSpecific
The union component used when dwRequestType is LINEPROXYREQUEST_AGENTSPECIFIC.
dwAddressID
The identifier of the address for which the agent status is to be retrieved.
dwAgentExtensionIDIndex
The index of the handler extension being invoked; the identifier's position within the array of extension identifiers returned in LINEAGENTCAPS.
dwSize
The total size in bytes of the Params parameter block.
Params
A block of memory that includes the contents passed to the handler from the application. If the handler is to return data to the application, it must be written into this parameter block before calling lineProxyResponse.
GetAgentActivityList
The union component used when dwRequestType is LINEPROXYREQUEST_GETAGENTACTIVITYLIST.
dwAddressID
The identifier of the address for which the agent activity list is to be retrieved.
ActivityList
A structure of type LINEAGENTACTIVITYLIST. Offsets within this structure are relative to the beginning of GetAgentActivityList.ActivityList rather than to the beginning of the LINEPROXYREQUEST structure. The dwTotalSize member is set by TAPI and the remaining bytes set to zero. The proxy handler must fill in dwNeededSize, dwUsedSize, and the remaining members as appropriate, before calling lineProxyResponse.
GetAgentGroupList
The union component used when dwRequestType is LINEPROXYREQUEST_GETAGENTGROUPLIST.
dwAddressID
The identifier of the address for which the agent group list is to be retrieved.
GroupList
A structure of type LINEAGENTGROUPLIST. Offsets within this structure are relative to the beginning of GetAgentGroupList.GroupList rather than to the beginning of the LINEPROXYREQUEST structure. The dwTotalSize member is set by TAPI and the remaining bytes set to zero. The proxy handler must fill in dwNeededSize, dwUsedSize, and the remaining members as appropriate, before calling lineProxyResponse.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.

See Also

lineProxyResponse


LINEREQMAKECALL

The LINEREQMAKECALL structure describes a tapiRequestMakeCall request.

typedef struct linereqmakecall_tag {
    char  szDestAddress[TAPIMAXDESTADDRESSSIZE];
    char  szAppName[TAPIMAXAPPNAMESIZE];
    char  szCalledParty[TAPIMAXCALLEDPARTYSIZE];
    char  szComment[TAPIMAXCOMMENTSIZE];
} LINEREQMAKECALL, FAR *LPLINEREQMAKECALL;

Members

szDestAddress[TAPIMAXADDRESSSIZE]
The NULL-terminated destination address of the make-call request. The address can use the canonical address format or the dialable address format. The maximum length of the address is TAPIMAXDESTADDRESSSIZE characters, which includes the NULL terminator. Longer strings are truncated.
szAppName[TAPIMAXAPPNAMESIZE]
The ASCII NULL-terminated user-friendly application name or filename of the application that originated the request. The maximum length of the address is TAPIMAXAPPNAMESIZE characters, which includes the NULL terminator.
szCalledParty[TAPIMAXCALLEDPARTYSIZE]
The ASCII NULL-terminated user-friendly called-party name. The maximum length of the called-party information is TAPIMAXCALLEDPARTYSIZE characters, which includes the NULL terminator.
szComment[TAPIMAXCOMMENTSIZE]
The ASCII NULL-terminated comment about the call request. The maximum length of the comment string is TAPIMAXCOMMENTSIZE characters, which includes the NULL terminator.

Remarks

No extensions.

The szDestAddress member contains the address of the remote party; the other members are useful for logging purposes. An application must use this structure to interpret the request buffer it received from lineGetRequest with the LINEREQUESTMODE_MAKECALL request mode.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

lineGetRequest, tapiRequestMakeCall


LINETERMCAPS

The LINETERMCAPS structure describes the capabilities of a line's terminal device.

typedef struct linetermcaps_tag {
    DWORD  dwTermDev;
    DWORD  dwTermModes;
    DWORD  dwTermSharing;
} LINETERMCAPS, FAR *LPLINETERMCAPS;

Members

dwTermDev
The device type of the terminal. This member uses the following LINETERMDEV_ constants:
LINETERMDEV_PHONE
The terminal is a phone set.
LINETERMDEV_HEADSET
The terminal is a headset.
LINETERMDEV_SPEAKER
The terminal is an external speaker and microphone.
dwTermModes
The terminal mode(s) the terminal device is able to deal with. This member uses the following LINETERMMODE_ constants:
LINETERMMODE_BUTTONS
Button-press events sent from the terminal to the line.
LINETERMMODE_LAMPS
Lamp events sent from the line to the terminal.
LINETERMMODE_DISPLAY
Display information sent from the line to the terminal.
LINETERMMODE_RINGER
Ringer-control information sent from the switch to the terminal.
LINETERMMODE_HOOKSWITCH
Hookswitch events sent from the terminal to the line.
LINETERMMODE_MEDIATOLINE
The unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIAFROMLINE
The unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIABIDIRECT
This is the bidirectional media stream associated with a call on the line and the terminal. Use this value when the routing of both unidirectional channels of a call's media stream cannot be controlled independently.
dwTermSharing
Specifies how the terminal device is shared between line devices. This member uses the following LINETERMSHARING_ constants:
LINETERMSHARING_PRIVATE
The terminal device is private to a single line device.
LINETERMSHARING_SHAREDEXCL
The terminal device can be used by multiple lines. The last line device to do a lineSetTerminal to the terminal for a given terminal mode has exclusive connection to the terminal for that mode.
LINETERMSHARING_SHAREDCONF
The terminal device can be used by multiple lines. The lineSetTerminal requests of the various terminals end up being "merged" at the terminal.

Remarks

No extensions.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

lineSetTerminal


LINETRANSLATECAPS

The LINETRANSLATECAPS structure describes the address translation capabilities.

typedef struct linetranslatecaps_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwNumLocations;
    DWORD  dwLocationListSize;
    DWORD  dwLocationListOffset;

    DWORD  dwCurrentLocationID;
    DWORD  dwNumCards;
    DWORD  dwCardListSize;
    DWORD  dwCardListOffset;

    DWORD  dwCurrentPreferredCardID;
} LINETRANSLATECAPS, FAR *LPLINETRANSLATECAPS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwNumLocations
The number of entries in the LocationList. It includes all locations defined, including zero (default).
dwLocationListSize
dwLocationListOffset
List of locations known to the address translation. The list consists of a sequence of LINELOCATIONENTRY structures. The dwLocationListOffset member points to the first byte of the first LINELOCATIONENTRY structure, and the dwLocationListSize member indicates the total number of bytes in the entire list.
dwCurrentLocationID
The dwPermanentLocationID member from the LINELOCATIONENTRY structure for the CurrentLocation.
dwNumCards
The number of entries in the CardList.
dwCardListSize
dwCardListOffset
List of calling cards known to the address translation. It includes only non-hidden card entries and always includes card 0 (direct dial). The list consists of a sequence of LINECARDENTRY structures. The dwCardListOffset member points to the first byte of the first LINECARDENTRY structure, and the dwCardListSize member indicates the total number of bytes in the entire list.
dwCurrentPreferredCardID
The dwPreferredCardID member from the LINELOCATIONENTRY structure for the CurrentLocation.

Remarks

No extensions.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINECARDENTRY, LINELOCATIONENTRY


LINETRANSLATEOUTPUT

The LINETRANSLATEOUTPUT structure describes the result of an address translation.

typedef struct linetranslateoutput_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwDialableStringSize;
    DWORD  dwDialableStringOffset;
    DWORD  dwDisplayableStringSize;
    DWORD  dwDisplayableStringOffset;

    DWORD  dwCurrentCountry;
    DWORD  dwDestCountry;
    DWORD  dwTranslateResults;
} LINETRANSLATEOUTPUT, FAR *LPLINETRANSLATEOUTPUT;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwDialableStringSize
dwDialableStringOffset
Contains the translated output that can be passed to the lineMakeCall, lineDial, or other function requiring a dialable string. The output is always a NULL-terminated ASCII string (NULL is accounted for in Size). Ancillary fields such as name and subaddress are included in this output string if they were in the input string. This string may contain private information such as calling card numbers. It should not be displayed to the user, to prevent inadvertent visibility to unauthorized persons.
dwDisplayableStringSize
dwDisplayableStringOffset
Contains the translated output that can be displayed to the user for confirmation. It is identical to DialableString, except that calling card digits are replaced with the "friendly name" of the card enclosed within bracket characters (for example, "[AT&T Card]"), and ancillary fields such as name and subaddress are removed. It should normally be safe to display this string in call-status dialog boxes without exposing private information to unauthorized persons. This information is also appropriate to include in call logs.
dwCurrentCountry
Contains the country code configured in CurrentLocation. This value may be used to control the display by the application of certain user interface elements, for local call progress tone detection, and for other purposes.
dwDestCountry
Contains the destination country code of the translated address. This value may be passed to the dwCountryCode parameter of lineMakeCall and other dialing functions (so that the call progress tones of the destination country such as a busy signal are properly detected). This field is set to zero if the destination address passed to lineTranslateAddress is not in canonical format.
dwTranslateResults
Indicates the information derived from the translation process, which may assist the application in presenting user-interface elements. This field uses the following LINETRANSLATERESULT_ constants:
LINETRANSLATERESULT_CANONICAL
Indicates that the input string was in valid canonical format.
LINETRANSLATERESULT_INTERNATIONAL
If this bit is on, the call is being treated as an international call (country code specified in the destination address is different from the country code specified for CurrentLocation).
LINETRANSLATERESULT_LONGDISTANCE
If this bit is on, the call is being treated as a long distance call (country code specified in the destination address is the same but area code is different from those specified for CurrentLocation).
LINETRANSLATERESULT_LOCAL
If this bit is on, the call is being treated as a local call (country code and area code specified in the destination address are the same as those specified for CurrentLocation).
LINETRANSLATERESULT_INTOLLLIST
If this bit is on, the local call is being dialed as long distance because the country has toll calling and the prefix appears in the TollPrefixList of CurrentLocation.
LINETRANSLATERESULT_NOTINTOLLLIST
If this bit is on, the country supports toll calling but the prefix does not appear in the TollPrefixList, so the call is dialed as a local call. If both INTOLLIST and NOTINTOLLIST are off, the current country does not support toll prefixes, and user interface elements related to toll prefixes should not be presented to the user; if either such bit is on, the country does support toll lists, and the related user interface elements should be enabled.
LINETRANSLATERESULT_DIALBILLING
Indicates that the returned address contains a "$".
LINETRANSLATERESULT_DIALQUIET
Indicates that the returned address contains a "@".
LINETRANSLATERESULT_DIALDIALTONE
Indicates that the returned address contains a "W".
LINETRANSLATERESULT_DIALPROMPT
Indicates that the returned address contains a "?".

Remarks

No extensions.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

lineDial, lineMakeCall, lineTranslateAddress


Phone Device Structures

The following is the reference for phone device structures.


PHONEBUTTONINFO

The PHONEBUTTONINFO structure contains information about a button on a phone device.

typedef struct phonebuttoninfo_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;
    DWORD  dwButtonMode;
    DWORD  dwButtonFunction;
    DWORD  dwButtonTextSize;
    DWORD  dwButtonTextOffset;
    DWORD  dwDevSpecificSize;
    DWORD  dwDevSpecificOffset;
    DWORD  dwButtonState;
} PHONEBUTTONINFO, FAR *LPPHONEBUTTONINFO;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwButtonMode
The mode or general usage class of the button. This member uses the following PHONEBUTTONMODE_ constants:
PHONEBUTTONMODE_DUMMY
This value is used to describe a button/lamp position that has no corresponding button but has only a lamp.
PHONEBUTTONMODE_CALL
The button is assigned to a call appearance.
PHONEBUTTONMODE_FEATURE
The button is assigned to requesting features from the switch, such as hold, conference, and transfer.
PHONEBUTTONMODE_KEYPAD
The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'.
PHONEBUTTONMODE_LOCAL
The button is a local function button, such as mute or volume control.
PHONEBUTTONMODE_DISPLAY
The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.
dwButtonFunction
The function assigned to the button. This member uses the PHONEBUTTONFUNCTION_ constants.
dwButtonTextSize
dwButtonTextOffset
The size in bytes of the variably sized field containing descriptive text for this button, and the offset in bytes from the beginning of this data structure. The format of this information is as specified in the dwStringFormat member of the phone's device capabilities.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes of the variably sized device-specific field, and the offset in bytes from the beginning of this data structure.
dwButtonState
For the phoneGetButtonInfo function, this field indicates the current state of the button, using the PHONEBUTTONSTATE_ constants. This field is ignored by the phoneSetButtonInfo function.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

Older applications are compiled without this field in the PHONEBUTTONINFO structure, and using a SIZEOF PHONEBUTTONINFO smaller than the new size. The application passes in a dwAPIVersion parameter with the phoneOpen function, which can be used for guidance by TAPI in handling this situation. If the application passes in a dwTotalSize less than the size of the fixed portion of the structure as defined in the specified dwAPIVersion, PHONEERR_STRUCTURETOOSMALL is returned. If sufficient memory has been allocated by the application, before calling TSPI_phoneGetButtonInfo, TAPI sets the dwNeededSize and dwUsedSize members to the fixed size of the structure as it existed in the specified API version.

New service providers (which support the new API version) must examine the API version passed in. If the API version is less than the highest version supported by the provider, the service provider must not fill in fields not supported in older API versions, as these would fall in the variable portion of the older structure.

New applications must be cognizant of the API version negotiated, and not examine the contents of fields in the fixed portion beyond the original end of the fixed portion of the structure for the negotiated API version.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

phoneGetButtonInfo, phoneOpen


PHONECAPS

The PHONECAPS structure describes the capabilities of a phone device.

typedef struct phonecaps_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;
    DWORD  dwProviderInfoSize;
    DWORD  dwProviderInfoOffset;
    DWORD  dwPhoneInfoSize;
    DWORD  dwPhoneInfoOffset;
    DWORD  dwPermanentPhoneID;
    DWORD  dwPhoneNameSize;
    DWORD  dwPhoneNameOffset;
    DWORD  dwStringFormat;
    DWORD  dwPhoneStates;
    DWORD  dwHookSwitchDevs;
    DWORD  dwHandsetHookSwitchModes;
    DWORD  dwSpeakerHookSwitchModes;
    DWORD  dwHeadsetHookSwitchModes;
    DWORD  dwVolumeFlags;
    DWORD  dwGainFlags;
    DWORD  dwDisplayNumRows;
    DWORD  dwDisplayNumColumns;
    DWORD  dwNumRingModes;
    DWORD  dwNumButtonLamps;
    DWORD  dwButtonModesSize;
    DWORD  dwButtonModesOffset;
    DWORD  dwButtonFunctionsSize;
    DWORD  dwButtonFunctionsOffset;
    DWORD  dwLampModesSize;
    DWORD  dwLampModesOffset;
    DWORD  dwNumSetData;
    DWORD  dwSetDataSize;
    DWORD  dwSetDataOffset;
    DWORD  dwNumGetData
    DWORD  dwGetDataSize;
    DWORD  dwGetDataOffset;
    DWORD  dwDevSpecificSize;
    DWORD  dwDevSpecificOffset;

    DWORD dwDeviceClassesSize;
    DWORD dwDeviceClassesOffset;
    DWORD dwPhoneFeatures;
    DWORD dwSettableHandsetHookSwitchModes;
    DWORD dwSettableSpeakerHookSwitchModes;
    DWORD dwSettableHeadsetHookSwitchModes;
    DWORD dwMonitoredHandsetHookSwitchModes;
    DWORD dwMonitoredSpeakerHookSwitchModes;
    DWORD dwMonitoredHeadsetHookSwitchModes;
} PHONECAPS, FAR *LPPHONECAPS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwProviderInfoSize
dwProviderInfoOffset
The size in bytes of the variably sized field containing service provider-specific information, and the offset in bytes from the beginning of this data structure.

The dwProviderInfoSize/Offset member provides information about the provider hardware and/or software, such as the vendor name and version numbers of hardware and software. This information can be useful when a user needs to call customer service with problems regarding the provider.

dwPhoneInfoSize
dwPhoneInfoOffset
The size in bytes of the variably sized device field containing phone-specific information, and the offset in bytes from the beginning of this data structure.

The dwPhoneInfoSize/Offset member provides information about the attached phone device, such as the phone device manufacturer, the model name, the software version, and so on. This information can be useful when a user needs to call customer service with problems regarding the phone.

dwPermanentPhoneID
The permanent DWORD identifier by which the phone device is known in the system's configuration.
dwPhoneNameSize
dwPhoneNameOffset
The size in bytes of the variably sized device field containing a user configurable name for this phone device, and the offset in bytes from the beginning of this data structure This name can be configured by the user when configuring the phone device's service provider and is provided for the user's convenience.
dwStringFormat
The string format to be used with this phone device. This member uses the following STRINGFORMAT_ constants:
STRINGFORMAT_ASCII
ASCII string format using one byte per character.
STRINGFORMAT_DBCS
DBCS string format using one or two bytes per character.
STRINGFORMAT_UNICODE
Unicode string format using two bytes per character.
dwPhoneStates
The state changes for this phone device for which the application can be notified in a PHONE_STATE message. This member uses the following PHONESTATE_ constants:
PHONESTATE_OTHER
Phone status items other than those listed below have changed. The application should check the current phone status to determine which items have changed.
PHONESTATE_CONNECTED
The connection between the phone device and TAPI was just made. This happens when TAPI is first invoked or when the wire connecting the phone to the PC is plugged in while TAPI is active.
PHONESTATE_DISCONNECTED
The connection between the phone device and TAPI was just broken. This happens when the wire connecting the phone set to the PC is unplugged while TAPI is active.
PHONESTATE_OWNER
The number of owners for the phone device has changed.
PHONESTATE_MONITORS
The number of monitors for the phone device has changed.
PHONESTATE_DISPLAY
The display of the phone has changed.
PHONESTATE_LAMP
A lamp of the phone has changed.
PHONESTATE_RINGMODE
The ring mode of the phone has changed.
PHONESTATE_RINGVOLUME
The ring volume of the phone has changed.
PHONESTATE_HANDSETHOOKSWITCH
The handset's hookswitch state has changed.
PHONESTATE_HANDSETVOLUME
The handset's speaker volume setting has changed.
PHONESTATE_HANDSETGAIN
The handset's microphone gain setting has changed.
PHONESTATE_SPEAKERHOOKSWITCH
The speakerphone's hookswitch state has changed.
PHONESTATE_SPEAKERVOLUME
The speakerphone's speaker volume setting has changed.
PHONESTATE_SPEAKERGAIN
The speakerphone's microphone gain setting state has changed.
PHONESTATE_HEADSETHOOKSWITCH
The headset's hookswitch state has changed.
PHONESTATE_HEADSETVOLUME
The headset's speaker volume setting has changed.
PHONESTATE_HEADSETGAIN
The headset's microphone gain setting has changed.
PHONESTATE_SUSPEND
The application's use of the phone is temporarily suspended.
PHONESTATE_RESUME
The application's use of the phone device is resumed after having been suspended for some time.
PHONESTATE_DEVSPECIFIC
The phone's device-specific information has changed.
PHONESTATE_REINIT
Items have changed in the configuration of phone devices. To become aware of these changes (as for the appearance of new phone devices) the application should reinitialize its use of TAPI.
PHONESTATE_CAPSCHANGE
Indicates that, due to configuration changes made by the user or other circumstances, one or more of the members in the PHONECAPS structure have changed. The application should use phoneGetDevCaps to read the updated structure.
PHONESTATE_REMOVED
Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). Normally, a PHONE_STATE message with this value is immediately followed by a PHONE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized result in PHONEERR_NODEVICE being returned to the application. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version do not receive any notification.
dwHookSwitchDevs
Specifies the phone's hookswitch devices. This member uses the following PHONEHOOKSWITCHDEV_ constants:
PHONEHOOKSWITCHDEV_HANDSET
The ubiquitous, handheld, ear- and mouthpiece.
PHONEHOOKSWITCHDEV_SPEAKER
A built-in loudspeaker and microphone. This could also be an externally connected adjunct to the telephone set.
PHONEHOOKSWITCHDEV_HEADSET
A headset connected to the phone set.
dwHandsetHookSwitchModes
dwSpeakerHookSwitchModes
dwHeadsetHookSwitchModes
Specifies the phone's hookswitch mode capabilities of the handset, speaker, or headset, respectively. The member is only meaningful if the hookswitch device is listed in dwHookSwitchDevs. This member uses the following PHONEHOOKSWITCHMODE_ constants:
PHONEHOOKSWITCHMODE_ONHOOK
The device's microphone and speaker are both onhook.
PHONEHOOKSWITCHMODE_MIC
The device's microphone is active, the speaker is mute.
PHONEHOOKSWITCHMODE_SPEAKER
The device's speaker is active, the microphone is mute.
PHONEHOOKSWITCHMODE_MICSPEAKER
The device's microphone and speaker are both active.
dwVolumeFlags
Specifies the volume setting capabilities of the phone device's speaker components. If the bit in position PHONEHOOKSWITCHDEV_ is TRUE, the volume of the corresponding hookswitch device's speaker component can be adjusted with phoneSetVolume; otherwise, FALSE.
dwGainFlags
Specifies the gain setting capabilities of the phone device's microphone components. If the bit position PHONEHOOKSWITCHDEV_ is TRUE, the volume of the corresponding hookswitch device's microphone component can be adjusted with phoneSetGain; otherwise, FALSE.
dwDisplayNumRows
Specifies the display capabilities of the phone device by describing the number of rows in the phone display. The dwDisplayNumRows and dwDisplayNumColumns members are both zero for a phone device without a display.
dwDisplayNumColumns
Specifies the display capabilities of the phone device by describing the number of columns in the phone display. The dwDisplayNumRows and dwDisplayNumColumns members are both zero for a phone device without a display.
dwNumRingModes
The ring capabilities of the phone device. The phone is able to ring with dwNumRingModes different ring patterns, identified as 1, 2, through dwNumRingModes minus one. If the value of this member is 0, applications have no control over the ring mode of the phone. If the value of this member is greater than 0, it indicates the number of ring modes in addition to silence that are supported by the service provider. A value of 0 in the lpdwRingMode parameter of phoneGetRing or the dwRingMode parameter of phoneSetRing indicates silence (the phone is not ringing or should not be rung), and dwRingMode values of 1 to dwNumRingModes are valid ring modes for the phone device.
dwNumButtonLamps
Specifies the number of button/lamps on the phone device that are detectable in TAPI. Button/lamps are identified by their identifier. Valid button/lamp identifiers range from zero to dwNumButtonLamps minus one. The keypad buttons '0', through '9', '*', and '#' are assigned the identifiers 0 through 12.
dwButtonModesSize
dwButtonModesOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field containing the button modes of the phone's buttons. The array is indexed by button/lamp identifier. This member uses the following PHONEBUTTONMODE_ constants:
PHONEBUTTONMODE_DUMMY
This value is used to describe a button/lamp position that has no corresponding button, but has only a lamp. If the phone provides any non-DUMMY buttons, the PHONE_BUTTON message is sent to the application if a button is pressed at the phone device.
PHONEBUTTONMODE_CALL
The button is assigned to a call appearance.
PHONEBUTTONMODE_FEATURE
The button is assigned to requesting features from the switch, such as hold, conference, and transfer.
PHONEBUTTONMODE_KEYPAD
The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'.
PHONEBUTTONMODE_LOCAL
The button is a local function button, such as mute or volume control.
PHONEBUTTONMODE_DISPLAY
The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.
dwButtonFunctionsSize
dwButtonFunctionsOffset
The size in bytes of the variably sized field containing the button modes of the phone's buttons, and the offset in bytes from the beginning of this data structure. This member uses the values specified by the PHONEBUTTONFUNCTION_ constants. The array is indexed by button/lamp identifier.
dwLampModesSize
dwLampModesOffset
The size in bytes of the variably sized field containing the lamp modes of the phone's lamps, and the offset in bytes from the beginning of this data structure. The array is indexed by button/lamp identifier. This member uses the following PHONELAMPMODE_ constants:
PHONELAMPMODE_BROKENFLUTTER
Broken flutter is the superposition of flash and flutter.
PHONELAMPMODE_FLASH
Flash means slow on and off.
PHONELAMPMODE_FLUTTER
Flutter means fast on and off.
PHONELAMPMODE_OFF
The lamp is off.
PHONELAMPMODE_STEADY
The lamp is continuously lit.
PHONELAMPMODE_WINK
The lamp is winking.
PHONELAMPMODE_DUMMY
This value is used to describe a button/lamp position that has no corresponding lamp.
dwNumSetData
The number of different download areas in the phone device. The different areas are referred to using the data IDs 0, 1, , dwNumSetData minus one. If this member is zero, the phone does not support the download capability.
dwSetDataSize
dwSetDataOffset
The size in bytes of the variably sized field containing the sizes (in bytes) of the phone's download data areas, and the offset in bytes from the beginning of this data structure. This is an array with DWORD-sized elements indexed by data identifier.
dwNumGetData
The number of different upload areas in the phone device. The different areas are referred to using the data IDs 0, 1, , dwNumGetData minus one. If this field is zero, the phone does not support the upload capability.
dwGetDataSize
dwGetDataOffset
The size in bytes of the variably sized field containing the sizes (in bytes) of the phone's upload data areas, and the offset in bytes from the beginning of this data structure. This is an array with DWORD-sized elements indexed by data identifier.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes of the variably sized device-specific field, and the offset in bytes from the beginning of this data structure.
dwDeviceClassesSize
dwDeviceClassesOffset
Length in bytes and offset from the beginning of PHONECAPS of a string consisting of the device class identifiers supported on this device for use with phoneGetID, separated by NULLs; the last identifier in the list is followed by two NULLs.
dwPhoneFeatures
These flags indicate which Telephony API functions can be invoked on the phone. A zero indicates the corresponding feature is not implemented and can never be invoked by the application on the phone; a one indicates the feature may be invoked depending on the device state and other factors. This member uses PHONEFEATURE_ constants.
dwSettableHandsetHookSwitchModes
The PHONEHOOKSWITCHMODE_ values that can be set on the handset using phoneSetHookSwitch.
dwSettableSpeakerHookSwitchModes
The PHONEHOOKSWITCHMODE_ values that can be set on the speakerphone using phoneSetHookSwitch.
dwSettableHeadsetHookSwitchModes
The PHONEHOOKSWITCHMODE_ values that can be set on the headset using phoneSetHookSwitch.
dwMonitoredHandsetHookSwitchModes
The PHONEHOOKSWITCHMODE_ values that can be detected and reported for the handset in a PHONE_STATE message and by phoneGetHookSwitch.
dwMonitoredSpeakerHookSwitchModes
The PHONEHOOKSWITCHMODE_ values that can be detected and reported for the speakerphone in a PHONE_STATE message and by phoneGetHookSwitch.
dwMonitoredHeadsetHookSwitchModes
The PHONEHOOKSWITCHMODE_ values that can be detected and reported for the headset in a PHONE_STATE message and by phoneGetHookSwitch.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

The members dwDeviceClassesSize through dwMonitoredHeadsetHookSwitchModes are available only to applications that open the phone device with an API version of 2.0 or later.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

PHONE_BUTTON, PHONE_CLOSE, PHONE_STATE, phoneGetDevCaps, phoneGetHookSwitch, phoneGetRing, phoneSetGain, phoneSetHookSwitch, phoneSetRing, phoneSetVolume


PHONEEXTENSIONID

The PHONEEXTENSIONID structure describes an extension identifier. Extension identifiers are used to identify service provider-specific extensions for phone device classes.

typedef struct phoneextensionid_tag {
    DWORD  dwExtensionID0;
    DWORD  dwExtensionID1;
    DWORD  dwExtensionID2;
    DWORD  dwExtensionID3;
} PHONEEXTENSIONID, FAR *LPPHONEEXTENSIONID;

Members

dwExtensionID0
dwExtensionID1
dwExtensionID2
dwExtensionID3
These four DWORD-sized members together specify a universally unique extension identifier that identifies a phone device class extension.

Remarks

No extensibility.

Extension identifiers are generated using an SDK-provided generation utility.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.


PHONEINITIALIZEEXPARAMS

typedef struct phoneinitializeexparams_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;
    DWORD  dwOptions;

  union
  {
    HANDLE hEvent;
    HANDLE hCompletionPort;
  } Handles;

    DWORD dwCompletionKey;

} PHONEINITIALIZEEXPARAMS, FAR *LPPHONEINITIALIZEEXPARAMS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwOptions
One of the PHONEINITIALIZEEXOPTION_ constants. Specifies the event notification mechanism the application desires to use.
hEvent
If dwOptions specifies PHONEINITIALIZEEXOPTION_USEEVENT, TAPI returns the event handle in this member.
hCompletionPort
If dwOptions specifies PHONEINITIALIZEEXOPTION_USECOMPLETIONPORT, the application must specify in this member the handle of an existing completion port opened using CreateIoCompletionPort.
dwCompletionKey
If dwOptions specifies PHONEINITIALIZEEXOPTION_USECOMPLETIONPORT, the application must specify in this field a value that is returned through the lpCompletionKey parameter of GetQueuedCompletionStatus to identify the completion message as a telephony message.

Remarks

See phoneInitializeEx for further information on these options.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.


PHONEMESSAGE

typedef struct phonemessage_tag {
    DWORD  hDevice;
    DWORD  dwMessageID;
    DWORD  dwCallbackInstance;
    DWORD  dwParam1;
    DWORD  dwParam2;
    DWORD  dwParam3;
} PHONEMESSAGE, FAR *LPPHONEMESSAGE;

Members

hDevice
A handle to a phone device.
dwMessageID
A phone message.
dwCallbackInstance
Instance data passed back to the application, which was specified by the application in phoneInitializeEx. This DWORD is not interpreted by TAPI.
dwParam1
A parameter for the message.
dwParam2
A parameter for the message.
dwParam3
A parameter for the message.

Remarks

For information about parameter values passed in this structure, see Phone Device Messages.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.

See Also

phoneInitializeEx


PHONESTATUS

The PHONESTATUS structure describes the current status of a phone device.

typedef struct phonestatus_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;
    DWORD  dwStatusFlags;
    DWORD  dwNumOwners;
    DWORD  dwNumMonitors;
    DWORD  dwRingMode;
    DWORD  dwRingVolume;
    DWORD  dwHandsetHookSwitchMode;
    DWORD  dwHandsetVolume;
    DWORD  dwHandsetGain;
    DWORD  dwSpeakerHookSwitchMode;
    DWORD  dwSpeakerVolume;
    DWORD  dwSpeakerGain;
    DWORD  dwHeadsetHookSwitchMode;
    DWORD  dwHeadsetVolume;
    DWORD  dwHeadsetGain;
    DWORD  dwDisplaySize;
    DWORD  dwDisplayOffset;
    DWORD  dwLampModesSize;
    DWORD  dwLampModesOffset;
    DWORD  dwOwnerNameSize;
    DWORD  dwOwnerNameOffset;
    DWORD  dwDevSpecificSize;
    DWORD  dwDevSpecificOffset;

    DWORD dwPhoneFeatures;
} PHONESTATUS, FAR *LPPHONESTATUS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwStatusFlags
Provides a set of status flags for this phone device. This member uses the following PHONESTATUSFLAGS_ constants:
PHONESTATUSFLAGS_CONNECTED
Specifies whether the phone is currently connected to TAPI. If connected, TRUE; otherwise, FALSE.
PHONESTATUSFLAGS_SUSPENDED
Specifies whether TAPI's manipulation of the phone device is suspended. If suspended, TRUE; otherwise, FALSE. An application's use of a phone device may be temporarily suspended when the switch wants to manipulate the phone in a way that cannot tolerate interference from the application.
dwNumOwners
The number of application modules with owner privilege for the phone.
dwNumMonitors
The number of application modules with monitor privilege for the phone.
dwRingMode
The current ring mode of a phone device.
dwRingVolume
The current ring volume of a phone device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum volume).
dwHandsetHookSwitchMode
The current hookswitch mode of the phone's handset. This member uses the following PHONEHOOKSWITCHMODE_ constants:
PHONEHOOKSWITCHMODE_ONHOOK
The device's microphone and speaker are both onhook.
PHONEHOOKSWITCHMODE_MIC
The device's microphone is active, the speaker is mute.
PHONEHOOKSWITCHMODE_SPEAKER
The device's speaker is active, the microphone is mute.
PHONEHOOKSWITCHMODE_MICSPEAKER
The device's microphone and speaker are both active.
dwHandsetVolume
The current speaker volume of the phone's handset device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum volume).
dwHandsetGain
The current microphone gain of the phone's handset device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum gain).
dwSpeakerHookSwitchMode
The current hookswitch mode of the phone's speakerphone. This member uses the following PHONEHOOKSWITCHMODE_ constants:
PHONEHOOKSWITCHMODE_ONHOOK
The device's microphone and speaker are both onhook.
PHONEHOOKSWITCHMODE_MIC
The device's microphone is active, the speaker is mute.
PHONEHOOKSWITCHMODE_SPEAKER
The device's speaker is active, the microphone is mute.
PHONEHOOKSWITCHMODE_MICSPEAKER
The device's microphone and speaker are both active.
dwSpeakerVolume
The current speaker volume of the phone's speaker device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum volume).
dwSpeakerGain
The current microphone gain of the phone's speaker device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum gain).
dwHeadsetHookSwitchMode
The current hookswitch mode of the phone's headset. This member uses the following PHONEHOOKSWITCHMODE_ constants:
PHONEHOOKSWITCHMODE_ONHOOK
The device's microphone and speaker are both onhook.
PHONEHOOKSWITCHMODE_MIC
The device's microphone is active, the speaker is mute.
PHONEHOOKSWITCHMODE_SPEAKER
The device's speaker is active, the microphone is mute.
PHONEHOOKSWITCHMODE_MICSPEAKER
The device's microphone and speaker are both active.
dwHeadsetVolume
The current speaker volume of the phone's headset device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum volume).
dwHeadsetGain
The current microphone gain of the phone's headset device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum gain).
dwDisplaySize
dwDisplayOffset
The size in bytes of the variably sized field containing the phone's current display information, and the offset in bytes, from the beginning of this data structure.
dwLampModesSize
dwLampModesOffset
The size in bytes of the variably sized field containing the phone's current lamp modes, and the offset in bytes from the beginning of this data structure.
dwOwnerNameSize
dwOwnerNameOffset
The size in bytes of the variably sized field containing the name of the application that is the current owner of the phone device, and the offset in bytes from the beginning of this data structure. The name is the application name provided by the application when it invoked with phoneInitialize or phoneInitializeEx. If no application name was supplied, the application's filename is used instead. If the phone currently has no owner, dwOwnerNameSize is zero.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes of the variably sized device-specific field, and the offset in bytes from the beginning of this data structure.
dwPhoneFeatures
These flags indicate which Telephony API functions can be invoked on the phone, considering the availability of the feature in the device capabilities, the current device state, and device ownership of the invoking application. A zero indicates the corresponding feature cannot be invoked by the application on the phone in its current state; a one indicates the feature can be invoked. This member uses PHONEFEATURE_ constants.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

The dwPhoneFeatures member is available only to applications that open the phone device with an API version of 2.0 or later.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

phoneInitialize, phoneInitializeEx


VARSTRING

The VARSTRING structure is used for returning variably sized strings. It is used both by the line device class and the phone device class.

typedef struct varstring_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;
    DWORD  dwStringFormat;
    DWORD  dwStringSize;
    DWORD  dwStringOffset;
} VARSTRING, FAR *LPVARSTRING;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwStringFormat
The format of the string. This member uses the following STRINGFORMAT_ constants:
STRINGFORMAT_ASCII
ASCII string format using one byte per character. The actual string is a NULL-terminated ASCII string with the terminating NULL accounted for in the string size.
STRINGFORMAT_DBCS
DBCS string format using one or two bytes per character.
STRINGFORMAT_UNICODE
Unicode string format using two bytes per character.
STRINGFORMAT_BINARY
An array of unsigned characters that could be used for numeric values.
dwStringSize
dwStringOffset
The size in bytes of the variably sized device field containing the string information, and the offset in bytes from the beginning of this data structure.

Remarks

No extensibility.

If a string cannot be returned in a variable structure, the dwStringSize and dwStringOffset members are set in one of these ways:

  • dwStringSize and dwStringOffset members are both set to zero.
  • dwStringOffset is nonzero and dwStringSize is zero.
  • dwStringOffset is nonzero, dwStringSize is 1, and the byte at the given offset is zero.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.


TAPI Messages

Messages are used to notify the application of asynchronous events. All of these messages are sent to the application through the message notification mechanism that the application specified in lineInitializeEx.

The message always contains a handle to the relevant object (phone, line, or call), which the application can determine the type of from the message type.

Certain messages are used to notify the application about a change in an object's status. These messages provide the object handle and give an indication of which status item has changed. The application can call the appropriate "get status" function of the object to obtain the object's full status.

When an event occurs, messages can be sent to zero, one, or more applications. The target applications for a message are determined by a number of different factors including the meaning of the message, the application's privilege to the object, whether or not the application initiated the request for which the message is a direct result, and the message masking that has been set by the application. Note the following points about messages:

  • Asynchronous reply messages are only sent to the application that originated the request and cannot be masked.
  • Messages that signal the completion of digit or tone generation or the gathering of digits are only sent to the application that requested the digit or tone generation.
  • Messages that indicate line or address state changes are sent to all applications that have opened the line, so long as the message has been enabled through lineSetStatusMessages.
  • Messages that indicate call state and call information changes are sent to all applications that have a handle to the call.
  • Messages that signal a digit detection, tone detection, or media mode detection are sent to the applications that requested monitoring of that event.

This section contains the reference for the following TAPI messages:

Line Device Messages

Phone Device Messages

Formatted Error Messages

Assisted Telephony Messages


Line Device Messages

The following section contains the reference for line device messages.


LINE_ADDRESSSTATE

The LINE_ADDRESSSTATE message is sent when the status of an address changes on a line that is currently open by the application. The application can invoke lineGetAddressStatus to determine the current status of the address.

LINE_ADDRESSSTATE
dwDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) idAddress;
dwParam2 = (DWORD) AddressState;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
A handle to the line device.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
The address identifier of the address that changed status.
dwParam2
The address state that changed. Can be a combination of these values:
LINEADDRESSSTATE_OTHER
Address-status items other than those listed below have changed. The application should check the current address status to determine which items have changed.
LINEADDRESSSTATE_DEVSPECIFIC
The device-specific item of the address status has changed.
LINEADDRESSSTATE_INUSEZERO
The address has changed to idle (it is now in use by zero stations).
LINEADDRESSSTATE_INUSEONE
The address has changed from idle or from being used by many bridged stations to being used by just one station.
LINEADDRESSSTATE_INUSEMANY
The monitored or bridged address has changed from being used by one station to being used by more than one station.
LINEADDRESSSTATE_NUMCALLS
The number of calls on the address has changed. This is the result of events such as a new inbound call, an outbound call on the address, or a call changing its hold status.
LINEADDRESSSTATE_FORWARD
The forwarding status of the address has changed, including the number of rings for determining a no-answer condition. The application should check the address status to determine details about the address's current forwarding status.
LINEADDRESSSTATE_TERMINALS
The terminal settings for the address have changed.
LINEADDRESSSTATE_CAPSCHANGE
Indicates that due to configuration changes made by the user or other circumstances one or more of the members in the LINEADDRESSCAPS structure for the address have changed. The application should use lineGetAddressCaps to read the updated structure. Applications that support API versions earlier than 1.4 receive a LINEDEVSTATE_REINIT message, requiring them to shutdown and reinitialize their connection to TAPI to obtain the updated information.
dwParam3
Unused.

Return Values

No return value.

Remarks

The LINE_ADDRESSSTATE message is sent to any application that has opened the line device and that has enabled this message. The sending of this message for the various status items can be controlled and queried using lineGetStatusMessages and lineSetStatusMessages. By default, address status reporting is disabled.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINEADDRESSCAPS, lineGetAddressCaps, lineGetAddressStatus, lineGetStatusMessages, lineSetStatusMessages


LINE_AGENTSPECIFIC

The LINE_AGENTSPECIFIC message is sent when the status of an ACD agent changes on a line the application currently has open. The application can invoke lineGetAgentStatus to determine the current status of the agent.

LINE_AGENTSPECIFIC
dwDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) dwInstanceData;
dwParam1 = (DWORD) dwAgentExtensionIDIndex;
dwParam2 = (DWORD) dwHandlerSpecific1;
dwParam3 = (DWORD) dwHandlerSpecific2;

Parameters

dwDevice
The application's handle to the line device.
dwCallbackInstance
The callback instance supplied when opening the call's line.
dwParam1
The index into the array of handler extension identifiers in the LINEAGENTCAPS structure of the handler extension with which the message is associated.
dwParam2
Specific to the handler extension. Generally, this value is used to cause the application to invoke a lineAgentSpecific function to fetch further details about the message.
dwParam3
Specific to the handler extension.

Return Values

No return value.

Remarks

The LINE_AGENTSPECIFIC message is not sent to applications that support older versions of TAPI.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.

See Also

LINEAGENTCAPS, lineAgentSpecific, lineGetAgentStatus


LINE_AGENTSTATUS

The LINE_AGENTSTATUS message is sent when the status of an ACD agent changes on a line the application currently has open. The application can invoke lineGetAgentStatus to determine the current status of the agent.

LINE_AGENTSTATUS
dwDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) dwInstanceData;
dwParam1 = (DWORD) dwAddressID;
dwParam2 = (DWORD) AgentStatus;
dwParam3 = (DWORD) AgentStatusDetail;

Parameters

dwDevice
The application's handle to the line device on which the agent status has changed.
dwCallbackInstance
The callback instance supplied when opening the call's line.
dwParam1
Identifier of the address on the line on which the agent status changed.
dwParam2
Specifies the agent status that has changed; can be a combination of LINEAGENTSTATUS_ constant values.
dwParam3
If dwParam2 includes the LINEAGENTSTATUS_STATE bit, then dwParam3 indicates the new value of the dwState member in LINEAGENTSTATUS. Otherwise, this parameter is set to zero.

Return Values

No return value.

Remarks

The LINE_AGENTSTATUS message is not sent to applications that support older versions of TAPI.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.

See Also

LINEAGENTSTATUS, lineGetAgentStatus


LINE_APPNEWCALL

The LINE_APPNEWCALL message is sent to inform an application when a new call handle has been spontaneously created on its behalf (other than through an API call from the application, in which case the handle would have been returned through a pointer parameter passed into the function).

LINE_APPNEWCALL
dwDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) dwInstanceData;
dwParam1 = (DWORD) dwAddressID;
dwParam2 = (DWORD) hCall;
dwParam3 = (DWORD) dwPrivilege;

Parameters

dwDevice
The application's handle to the line device on which the call has been created.
dwCallbackInstance
The callback instance supplied when opening the call's line.
dwParam1
Identifier of the address on the line on which the call appears.
dwParam2
The application's handle to the new call.
dwParam3
The applications privilege to the new call (LINECALLPRIVILEGE_OWNER or LINECALLPRIVILEGE_MONITOR).

Return Values

No return value.

Comments and Backward Compatibility

Applications supporting TAPI version 2.0 or later are sent a LINE_APPNEWCALL message whenever the application is spontaneously given a handle to a new call. Because the message includes the hLine and dwAddressID parameters on which the call exists, the application can readily create a new call object in the correct context. The LINE_APPNEWCALL message is always immediately followed by a LINE_CALLSTATE message indicating the initial state of the call.

Older applications (that negotiated an API version earlier than 2.0) are sent only a LINE_CALLSTATE message, as documented in previous versions of the API. Such applications would create a new call object upon receiving a LINE_CALLSTATE message that has dwParam3 set to a nonzero value and containing a call handle not presently known by the application. The disadvantages are that (a) the application must call lineGetCallInfo to determine the hLine and dwAddressID parameters associated with the call; (b) the application must scan all known call handles to determine that the call is a new call; and (c) it is possible, under certain conditions, for the application to think it is receiving a new call handle when in reality it has just deallocated its handle to the call (for example, the application has just deallocated a call handle, but a LINE_CALLSTATE message giving the application ownership of the call due to a lineHandoff from another application was already in the application's TAPI message queue).

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.

See Also

LINE_CALLSTATE, lineGetCallInfo, lineHandoff


LINE_CALLINFO

The LINE_CALLINFO message is sent when the call information about the specified call has changed. The application can invoke lineGetCallInfo to determine the current call information.

LINE_CALLINFO
dwDevice = (DWORD) hCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) CallInfoState;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
A handle to the call.
dwCallbackInstance
The callback instance supplied when opening the call's line.
dwParam1
The call information item that has changed. Can be a combination of these values:
LINECALLINFOSTATE_OTHER
Information items other than those listed below have changed. The application should check the current call information to determine which items have changed.
LINECALLINFOSTATE_DEVSPECIFIC
The device-specific field of the call-information record has changed.
LINECALLINFOSTATE_BEARERMODE
The bearer mode field of the call-information record has changed.
LINECALLINFOSTATE_RATE
The rate field of the call-information record has changed.
LINECALLINFOSTATE_MEDIAMODE
The media mode field of the call-information record has changed.
LINECALLINFOSTATE_APPSPECIFIC
The application-specific field of the call-information record has changed.
LINECALLINFOSTATE_CALLID
The call identifier field of the call-information record has changed.
LINECALLINFOSTATE_RELATEDCALLID
The related call identifier field of the call-information record has changed.
LINECALLINFOSTATE_ORIGIN
The origin field of the call-information record has changed.
LINECALLINFOSTATE_REASON
The reason field of the call-information record has changed.
LINECALLINFOSTATE_COMPLETIONID
The completion identifier field of the call-information record has changed.
LINECALLINFOSTATE_NUMOWNERINCR
The number of owner fields in the call-information record was increased.
LINECALLINFOSTATE_NUMOWNERDECR
The number of owner fields in the call-information record was decreased.
LINECALLINFOSTATE_NUMMONITORS
The number of monitors fields in the call-information record has changed.
LINECALLINFOSTATE_TRUNK
The trunk field of the call information record has changed.
LINECALLINFOSTATE_CALLERID
One of the callerID-related fields of the call information record has changed.
LINECALLINFOSTATE_CALLEDID
One of the calledID-related fields of the call information record has changed.
LINECALLINFOSTATE_CONNECTEDID
One of the connectedID-related fields of the call information record has changed.
LINECALLINFOSTATE_REDIRECTIONID
One of the redirectionID-related fields of the call information record has changed.
LINECALLINFOSTATE_REDIRECTINGID
One of the redirectingID-related fields of the call information record has changed.
LINECALLINFOSTATE_DISPLAY
The display field of the call information record has changed.
LINECALLINFOSTATE_USERUSERINFO
The user-user information of the call information record has changed.
LINECALLINFOSTATE_HIGHLEVELCOMP
The high-level compatibility field of the call information record has changed.
LINECALLINFOSTATE_LOWLEVELCOMP
The low-level compatibility field of the call information record has changed.
LINECALLINFOSTATE_CHARGINGINFO
The charging information of the call information record has changed.
LINECALLINFOSTATE_TERMINAL
The terminal mode information of the call information record has changed.
LINECALLINFOSTATE_DIALPARAMS
The dial parameters of the call information record has changed.
LINECALLINFOSTATE_MONITORMODES
One or more of the digit, tone, or media monitoring fields in the call information record has changed.
dwParam2
Unused.
dwParam3
Unused.

Return Values

No return value.

Remarks

A LINE_CALLINFO message with a NumOwnersIncr, NumOwnersDecr, and/or NumMonitorsChanged indication is sent to applications that already have a handle for the call. This can be the result of another application changing ownership or monitorship to a call with lineOpen, lineClose, lineShutdown, lineSetCallPrivilege, lineGetNewCalls, and lineGetConfRelatedCalls.

These LINE_CALLINFO messages are not sent when a notification of a new call is provided in a LINE_CALLSTATE message, because the call information already reflects the correct number of owners and monitors at the time the LINE_CALLSTATE messages are sent. LINE_CALLINFO messages are also suppressed in the case where a call is offered by TAPI to monitors through the LINECALLSTATE_UNKNOWN mechanism.

Note The application that causes a change in the number of owners or monitors (for example, by invoking lineDeallocateCall or lineSetCallPrivilege) does not itself receive a message indicating that the change has been done.

No LINE_CALLINFO messages are sent for a call after the call has entered the idle state. Specifically, changes in the number of owners and monitors are not reported as applications deallocate their handles for the idle call.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

lineClose, lineDeallocateCall, lineGetCallInfo, lineGetConfRelatedCalls, lineGetNewCalls, lineOpen, lineSetCallPrivilege, lineShutdown


LINE_CALLSTATE

The LINE_CALLSTATE message is sent when the status of the specified call has changed. Typically, several such messages are received during the lifetime of a call. Applications are notified of new incoming calls with this message; the new call is in the offering state. The application can use lineGetCallStatus to retrieve more detailed information about the current status of the call.

LINE_CALLSTATE
dwDevice = (DWORD) hCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) CallState;
dwParam2 = (DWORD) CallStateDetail;
dwParam3 = (DWORD) CallPrivilege;

Parameters

dwDevice
A handle to the call.
dwCallbackInstance
The callback instance supplied when opening the call's line.
dwParam1
The new call state. This parameter must be one and only one of the following LINECALLSTATE_ values:
LINECALLSTATE_IDLE
The call is idle—no call actually exists.
LINECALLSTATE_OFFERING
The call is being offered to the station, signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user. Alerting is done by the switch instructing the line to ring; it does not affect any call states.
LINECALLSTATE_ACCEPTED
The call was offering and has been accepted. This indicates to other (monitoring) applications that the current owner application has claimed responsibility for answering the call. In ISDN, this also indicates that alerting to both parties has started.
LINECALLSTATE_DIALTONE
The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number.
LINECALLSTATE_DIALING
Destination address information (a phone number) is being sent to the switch over the call. Note that lineGenerateDigits does not place the line into the dialing state.
LINECALLSTATE_RINGBACK
The call is receiving ringback from the called address. Ringback indicates that the other station has been reached and is being alerted.
LINECALLSTATE_BUSY
The call is receiving a busy tone. Busy tone indicates that the call cannot be completed—either a circuit (trunk) or the remote party's station are in use.
LINECALLSTATE_SPECIALINFO
Special information is sent by the network. Special information is typically sent when the destination cannot be reached.
LINECALLSTATE_CONNECTED
The call has been established and the connection is made. Information is able to flow over the call between the originating address and the destination address.
LINECALLSTATE_PROCEEDING
Dialing has completed and the call is proceeding through the switch or telephone network.
LINECALLSTATE_ONHOLD
The call is on hold by the switch.
LINECALLSTATE_CONFERENCED
The call is currently a member of a multiparty conference call.
LINECALLSTATE_ONHOLDPENDCONF
The call is currently on hold while it is being added to a conference.
LINECALLSTATE_ONHOLDPENTRANSFER
The call is currently on hold awaiting transfer to another number.
LINECALLSTATE_DISCONNECTED
The remote party has disconnected from the call.
LINECALLSTATE_UNKNOWN
The state of the call is not known. This may be due to limitations of the call-progress detection implementation.
dwParam2
Call-state-dependent information.

If dwParam1 is LINECALLSTATE_BUSY, dwParam2 contains details about the busy mode. This parameter uses the following LINEBUSYMODE_ constants:

LINEBUSYMODE_STATION
The busy signal indicates that the called party's station is busy. This is usually signaled by means of a "normal" busy tone.
LINEBUSYMODE_TRUNK
The busy signal indicates that a trunk or circuit is busy. This is usually signaled with a "long" busy tone.
LINEBUSYMODE_UNKNOWN
The busy signal's specific mode is currently unknown, but may become known later.
LINEBUSYMODE_UNAVAIL
The busy signal's specific mode is unavailable and cannot become known.

If dwParam1 is LINECALLSTATE_CONNECTED, dwParam2 contains details about the connected mode. This parameter uses the following LINECONNECTEDMODE_ constants:

LINECONNECTEDMODE_ACTIVE
Indicates that the call is connected at the current station (the current station is a participant in the call).
LINECONNECTEDMODE_INACTIVE
Indicates that the call is active at one or more other stations, but the current station is not a participant in the call.

If dwParam1 is LINECALLSTATE_DIALTONE, dwParam2 contains the details about the dial tone mode. This parameter uses the following LINEDIALTONEMODE_ constants:

LINEDIALTONEMODE_NORMAL
This is a "normal" dial tone, which typically is a continuous tone.
LINEDIALTONEMODE_SPECIAL
This is a special dial tone indicating that a certain condition is currently in effect.
LINEDIALTONEMODE_INTERNAL
This is an internal dial tone, as within a PBX.
LINEDIALTONEMODE_EXTERNAL
This is an external (public network) dial tone.
LINEDIALTONEMODE_UNKNOWN
The dial tone mode is currently unknown, but may become known later.
LINEDIALTONEMODE_UNAVAIL
The dial tone mode is unavailable and cannot become known.

If dwParam1 is LINECALLSTATE_OFFERING, dwParam2 contains details about the connected mode. This parameter uses the following LINEOFFERINGMODE_ constants:

LINEOFFERINGMODE_ACTIVE
Indicates that the call is alerting at the current station (is accompanied by LINEDEVSTATE_RINGING messages), and if any application is set up to automatically answer, it may do so.
LINEOFFERINGMODE_INACTIVE
Indicates that the call is being offered at more than one station, but the current station is not alerting (for example, it may be an attendant station where the offering status is advisory, such as blinking a light).

If dwParam1 is LINECALLSTATE_SPECIALINFO, dwParam2 contains the details about the special information mode. This parameter uses the following LINESPECIALINFO_ constants:

LINESPECIALINFO_NOCIRCUIT
This special information tone precedes a "no circuit" or emergency announcement (trunk blockage category).
LINESPECIALINFO_CUSTIRREG
This special information tone precedes a vacant number, AIS, Centrex number change and nonworking station, access code not dialed or dialed in error, or manual intercept operator message (customer irregularity category).
LINESPECIALINFO_REORDER
This special information tone precedes a reorder announcement (equipment irregularity category).
LINESPECIALINFO_UNKNOWN
Specifics about the special information tone are currently unknown but may become known later.
LINESPECIALINFO_UNAVAIL
Specifics about the special information tone are unavailable and cannot become known.

If dwParam1 is LINECALLSTATE_DISCONNECTED, dwParam2 contains details about the disconnect mode. This parameter uses the following LINEDISCONNECTMODE_ constants:

LINEDISCONNECTMODE_NORMAL
This is a "normal" disconnect request by the remote party, the call was terminated normally.
LINEDISCONNECTMODE_UNKNOWN
The reason for the disconnect request is unknown.
LINEDISCONNECTMODE_REJECT
The remote user has rejected the call.
LINEDISCONNECTMODE_PICKUP
The call was picked up from elsewhere.
LINEDISCONNECTMODE_FORWARDED
The call was forwarded by the switch.
LINEDISCONNECTMODE_BUSY
The remote user's station is busy.
LINEDISCONNECTMODE_NOANSWER
The remote user's station does not answer.
LINEDISCONNECTMODE_NODIALTONE
A dial tone was not detected within a service-provider defined timeout, at a point during dialing when one was expected (such as at a "W" in the dialable string). This can also occur without a service-provider-defined timeout period or without a value specified in the dwWaitForDialTone member of the LINEDIALPARAMS structure.
LINEDISCONNECTMODE_BADADDRESS
The destination address in invalid.
LINEDISCONNECTMODE_UNREACHABLE
The remote user could not be reached.
LINEDISCONNECTMODE_CONGESTION
The network is congested.
LINEDISCONNECTMODE_INCOMPATIBLE
The remote user's station equipment is incompatible for the type of call requested.
LINEDISCONNECTMODE_UNAVAIL
The reason for the disconnect is unavailable and cannot become known later.

Note In circumstances where a delayed response is appropriate, use LINEDISCONNECTMODE_TEMPFAILURE. Where a blacklisted response is appropriate, use LINEDISCONNECT_BLOCKED. For further information, see LINEDISCONNECTMODE_ Constants.

If dwParam1 is LINECALLSTATE_CONFERENCED, dwParam2 contains the hConfCall parameter of the parent call of the conference of which the subject hCall is a member. If the call specified in dwParam2 was not previously considered by the application to be a parent conference call (hConfCall), the application must do so as a result of this message. If the application does not have a handle to the parent call of the conference (because it has previously called lineDeallocateCall on that handle) dwParam2 is set to NULL.

dwParam3
If zero, this parameter indicates that there has been no change in the application's privilege for the call.

If nonzero, it specifies the application's privilege to the call. This occurs in the following situations: (1) The first time that the application is given a handle to this call; (2) When the application is the target of a call handoff (even if the application already was an owner of the call). This parameter uses the following LINECALLPRIVILEGE_ constants:

LINECALLPRIVILEGE_MONITOR
The application has monitor privilege.
LINECALLPRIVILEGE_OWNER
The application has owner privilege.

Return Values

No return value.

Remarks

This message is sent to any application that has a handle for the call. The LINE_CALLSTATE message also notifies applications that monitor calls on a line about the existence and state of outbound calls established by other applications or manually by the user (for example, on an attached phone device). The call state of such calls reflects the actual state of the call, which is not offering. By examining the call state, the application can determine whether the call is an inbound call that needs to be answered or not.

A LINE_CALLSTATE message with an unknown call state can be sent to a monitoring application as the result of a successful lineMakeCall, lineForward, lineUnpark, lineSetupTransfer, linePickup, lineSetupConference, or linePrepareAddToConference that has been requested by another application. At the same time that the requesting application is sent a LINE_REPLY (success) for the requested operation, any monitoring applications on the line are sent the LINE_CALLSTATE (unknown) message. A LINE_CALLSTATE message indicating the "real" call state of the newly generated call is sent (using information provided by the service provider) to the requesting and monitoring applications shortly thereafter.

A LINE_CALLSTATE (unknown) message is sent to monitoring applications only if lineCompleteTransfer causes calls to be resolved into a three-way conference.

For backward compatibility, older applications are not expecting any particular value in dwParam2 of a LINECALLSTATE_CONFERENCED message. TAPI therefore passes the parent call hConfCall in dwParam2 regardless of the API version of the application receiving the message. In the case of a conference call initiated by the service provider, the older application is not aware that the parent call has become a conference call unless it happens to spontaneously examine other information (for example, call lineGetConfRelatedCalls)

This message cannot be disabled.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINE_REPLY, lineCompleteTransfer, lineDeallocateCall, LINEDIALPARAMS, lineForward, lineGenerateDigits, lineGetCallStatus, lineGetConfRelatedCalls, lineMakeCall, linePickup, linePrepareAddToConference, lineSetupTransfer, lineUnpark


LINE_CLOSE

The LINE_CLOSE message is 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.

LINE_CLOSE
dwDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) 0;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
A handle to the line device that was closed. This handle is no longer valid.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
Unused.
dwParam2
Unused.
dwParam3
Unused.

Return Values

No return value.

Remarks

The LINE_CLOSE message is only sent to any application after an open line has been forcibly closed. This can be done to prevent a single application from monopolizing a line device for too long. Whether or not the line can be reopened immediately after a forced close is device-specific.

A line device can also be forcibly closed after the user has modified the configuration of that line or its driver. If the user wants the configuration changes to be effective immediately (as opposed to after the next system restart), and they affect the application's current view of the device (such as a change in device capabilities), then a service provider can forcibly close the line device.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.


LINE_CREATE

The LINE_CREATE message is sent to inform the application of the creation of a new line device.

LINE_CREATE
dwDevice = (DWORD) 0;
dwCallbackInstance = (DWORD) 0;
dwParam1 = (DWORD) idDevice;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
Unused.
dwCallbackInstance
Unused.
dwParam1
The dwDeviceID of the newly created device.
dwParam2
Unused.
dwParam3
Unused.

Return Values

No return value.

Remarks

Older applications (that negotiated TAPI version 1.3) are sent a LINE_LINEDEVSTATE message specifying LINEDEVSTATE_REINIT, which requires them to shut down their use of the API and call lineInitialize again to obtain the new number of devices. Unlike previous versions of TAPI, however, this version does not require all applications to shut down before allowing applications to reinitialize; reinitialization can take place immediately when a new device is created (complete shutdown is still required when a service provider is removed from the system).

Applications supporting TAPI version 1.4 or later are sent a LINE_CREATE message. This informs them of the existence of the new device and its new device identifier. The application can then choose whether or not to attempt working with the new device at its leisure. This message is sent to all applications supporting this or subsequent versions of the API that have called lineInitialize or lineInitalizeEx, including those that do not have any line devices open at the time.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINE_LINEDEVSTATE, lineInitialize, lineInitializeEx


LINE_DEVSPECIFIC

The LINE_DEVSPECIFIC message is 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 are device specific.

LINE_DEVSPECIFIC
dwDevice = (DWORD) hLineOrCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) DeviceSpecific1;
dwParam2 = (DWORD) DeviceSpecific2;
dwParam3 = (DWORD) DeviceSpecific3;

Parameters

dwDevice
A handle to either a line device or call. This is device specific.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Return Values

No return value.

Remarks

The LINE_DEVSPECIFIC message is used by a service provider in conjunction with the lineDevSpecific function. Its meaning is device specific.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.


LINE_DEVSPECIFICFEATURE

The LINE_DEVSPECIFICFEATURE message is 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 are device specific.

LINE_DEVSPECIFICFEATURE
dwDevice = (DWORD) hLineOrCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) DeviceSpecific1;
dwParam2 = (DWORD) DeviceSpecific2;
dwParam3 = (DWORD) DeviceSpecific3;

Parameters

dwDevice
A handle to either a line device or call. This is device specific.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Return Values

No return value.

Remarks

The LINE_DEVSPECIFICFEATURE message is used by a service provider in conjunction with the lineDevSpecificFeature function. Its meaning is device specific.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.


LINE_GATHERDIGITS

The LINE_GATHERDIGITS message is sent when the current buffered digit-gathering request has terminated or is canceled. The digit buffer can be examined after this message has been received by the application.

LINE_GATHERDIGITS
dwDevice = (DWORD) hCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) GatherTermination;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
A handle to the call.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
The reason why digit gathering was terminated. This parameter must be one and only one of the following LINEGATHERTERM_ constants:
LINEGATHERTERM_BUFFERFULL
The requested number of digits has been gathered. The buffer is full.
LINEGATHERTERM_TERMDIGIT
One of the termination digits matched a received digit. The matched termination digit is the last digit in the buffer.
LINEGATHERTERM_FIRSTTIMEOUT
The first digit timeout expired. The buffer contains no digits.
LINEGATHERTERM_INTERTIMEOUT
The inter-digit timeout expired. The buffer contains at least one digit.
LINEGATHERTERM_CANCEL
The request was canceled by this application, by another application, or because the call terminated.
dwParam2
Unused.
dwParam3
The "tick count" (number of milliseconds since Windows started) at which the digit gathering completed. For API versions ealier than 2.0, this parameter is unused.

Return Values

No return value.

Remarks

The LINE_GATHERDIGITS message is only sent to the application that initiated the digit gathering on the call using lineGatherDigits.

If the lineGatherDigits function is used to cancel a previous request to gather digits, TAPI sends a LINE_GATHERDIGITS message with dwParam1 set to LINEGATHERTERM_CANCEL to the application indicating that the originally specified buffer contains the digits gathered up to the cancellation.

Because the timestamp specified by dwParam3 may have been generated on a computer other than the one on which the application is executing, it is useful only for comparison to other similarly timestamped messages generated on the same line device (LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORMEDIA, LINE_MONITORTONE), in order to determine their relative timing (separation between events). The tick count can "wrap around" after approximately 49.7 days; applications must take this into account when performing calculations.

If the service provider does not generate the timestamp (for example, if it was created using an earlier version of TAPI), then TAPI provides a timestamp at the point closest to the service provider generating the event so that the synthesized timestamp is as accurate as possible.

Note When an application invokes any asynchronous operation that writes data back into application memory, the application must keep that memory available for writing until a LINE_REPLY or LINE_GATHERDIGITS message is received.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORMEDIA, LINE_MONITORTONE, LINE_REPLY, lineGatherDigits


LINE_GENERATE

The LINE_GENERATE message is sent to notify the application that the current digit or tone generation has terminated. Only one such generation request can be in progress an a given call at any time. This message is also sent when digit or tone generation is canceled.

LINE_GENERATE
dwDevice = (DWORD) hCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) GenerateTermination;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
A handle to the call.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
The reason why digit or tone generation was terminated. This parameter must be one and only one of the following LINEGENERATETERM_ constants:
LINEGENERATETERM_DONE
The requested number of digits have been generated, or the requested tones have been generated for the requested duration.
LINEGENERATETERM_CANCEL
The digit or tone generation request was canceled by this application, by another application, or because the call terminated.
dwParam2
Unused.
dwParam3
The "tick count" (number of milliseconds since Windows started) at which the digit or tone generation completed. For API versions earlier than 2.0, this parameter is unused.

Return Values

No return value.

Remarks

The LINE_GENERATE message is only sent to the application that requested the digit or tone generation.

Because the timestamp specified by dwParam3 may have been generated on a computer other than the one on which the application is executing, it is useful only for comparison to other similarly timestamped messages generated on the same line device (LINE_GATHERDIGITS, LINE_MONITORDIGITS, LINE_MONITORMEDIA, LINE_MONITORTONE), in order to determine their relative timing (separation between events). The tick count can "wrap around" after approximately 49.7 days; applications must take this into account when performing calculations.

If the service provider does not generate the timestamp (for example, if it was created using an earlier version of TAPI), then TAPI provides a timestamp at the point closest to the service provider generating the event so that the synthesized timestamp is as accurate as possible.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINE_GATHERDIGITS, LINE_MONITORDIGITS, LINE_MONITORMEDIA, LINE_MONITORTONE


LINE_LINEDEVSTATE

The LINE_LINEDEVSTATE message is sent when the state of a line device has changed. The application can invoke lineGetLineDevStatus to determine the new status of the line.

LINE_LINEDEVSTATE
dwDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) DeviceState;
dwParam2 = (DWORD) DeviceStateDetail1;
dwParam3 = (DWORD) DeviceStateDetail2;

Parameters

dwDevice
A handle to the line device. This parameter is NULL when dwParam1 is LINEDEVSTATE_REINIT.
dwCallbackInstance
The callback instance supplied when opening the line. If the dwParam1 parameter is LINEDEVSTATE_REINIT, the dwCallbackInstance parameter is not valid and is set to zero.
dwParam1
The line device status item that has changed. The parameter can be a combination of the following LINEDEVSTATE_ constants:
LINEDEVSTATE_OTHER
Device status items other than those listed below have changed. The application should check the current device status to determine which items have changed.
LINEDEVSTATE_RINGING
The switch tells the line to alert the user. Service providers notify applications on each ring cycle by sending messages containing this constant. For example, in the United States, service providers send a message with this constant every six seconds.
LINEDEVSTATE_CONNECTED
The line was previously disconnected and is now connected to TAPI.
LINEDEVSTATE_DISCONNECTED
This line was previously connected and is now disconnected from TAPI.
LINEDEVSTATE_MSGWAITON
The "message waiting" indicator is turned on.
LINEDEVSTATE_MSGWAITOFF
The "message waiting" indicator is turned off.
LINEDEVSTATE_NUMCOMPLETIONS
The number of outstanding call completions on the line device has changed.
LINEDEVSTATE_INSERVICE
The line is connected to TAPI. This happens when TAPI is first activated, or when the line wire is physically plugged in and in service at the switch while TAPI is active.
LINEDEVSTATE_OUTOFSERVICE
The line is out of service at the switch or physically disconnected. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_MAINTENANCE
Maintenance is being performed on the line at the switch. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_OPEN
The line has been opened by another application.
LINEDEVSTATE_CLOSE
The line has been closed by another application.
LINEDEVSTATE_NUMCALLS
The number of calls on the line device has changed.
LINEDEVSTATE_TERMINALS
The terminal settings have changed.
LINEDEVSTATE_ROAMMODE
The roaming state of the line device has changed.
LINEDEVSTATE_BATTERY
The battery level has changed significantly (cellular).
LINEDEVSTATE_SIGNAL
The signal level has changed significantly (cellular).
LINEDEVSTATE_DEVSPECIFIC
The line's device-specific information has changed.
LINEDEVSTATE_REINIT
Items have changed in the configuration of line devices. To become aware of these changes (as with the appearance of new line devices), the application should reinitialize its use of TAPI. The dwDevice parameter is left NULL for this state change as it applies to any of the lines in the system.
LINEDEVSTATE_LOCK
The locked status of the line device has changed. (For more information, refer to the description of the LINEDEVSTATUSFLAGS_LOCKED bit of the LINEDEVSTATUSFLAGS_ constants.)
LINEDEVSTATE_CAPSCHANGE
Indicates that, due to configuration changes made by the user or other circumstances, one or more of the members in the LINEDEVCAPS structure for the address have changed. The application should use lineGetDevCaps to read the updated structure.
LINEDEVSTATE_CONFIGCHANGE
Indicates that configuration changes have been made to one or more of the media devices associated with the line device. The application, if it desires, can use lineGetDevConfig to read the updated information.
LINEDEVSTATE_TRANSLATECHANGE
Indicates that, due to configuration changes made by the user or other circumstances, one or more of the members in the LINETRANSLATECAPS structure have changed. The application should use lineGetTranslateCaps to read the updated structure.
LINEDEVSTATE_COMPLCANCEL
Indicates that the call completion identified by the completion identifier contained in parameter dwParam2 of the LINE_LINEDEVSTATE message has been externally canceled and is no longer considered valid (if that value were to be passed in a subsequent call to lineUncompleteCall, the function would fail with LINEERR_INVALCOMPLETIONID).
LINEDEVSTATE_REMOVED
Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). Normally, a LINE_LINEDEVSTATE message with this value is immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version do not receive any notification.
dwParam2
The interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING, dwParam2 contains the ring mode with which the switch instructs the line to ring. Valid ring modes are numbers in the range one to dwNumRingModes, where dwNumRingModes is a line device capability.

If dwParam1 is LINEDEVSTATE_REINIT, and the message was issued by TAPI as a result of translation of a new API message into a REINIT message, then dwParam2 contains the dwMsg parameter of the original message (for example, LINE_CREATE or LINE_LINEDEVSTATE). If dwParam2 is zero, this indicates that the REINIT message is a "real" REINIT message that requires the application to call lineShutdown at its earliest convenience.

dwParam3
The interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING, dwParam3 contains the ring count for this ring event. The ring count starts at zero.

If dwParam1 is LINEDEVSTATE_REINIT, and the message was issued by TAPI as a result of translation of a new API message into a REINIT message, then dwParam3 contains the dwParam1 parameter of the original message (for example, LINEDEVSTATE_TRANSLATECHANGE or some other LINEDEVSTATE_ value, if dwParam2 is LINE_LINEDEVSTATE, or the new device identifier, if dwParam2 is LINE_CREATE).

Return Values

No return value.

Remarks

The sending of the LINE_LINEDEVSTATE message can be controlled with lineSetStatusMessages. An application can indicate status item changes about which it wants to be notified. By default, all status reporting is disabled except for LINEDEVSTATE_REINIT, which cannot be disabled. This message is sent to all applications that have a handle to the line, including those that called lineOpen with the dwPrivileges parameter set to LINECALLPRIVILEGE_NONE, LINECALLPRIVILEGE_OWNER, LINECALLPRIVILEGE_MONITOR, or permitted combinations of these.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINE_CLOSE, LINE_CREATE, LINEDEVCAPS, lineGetDevCaps, lineGetDevConfig, lineGetTranslateCaps, lineInitialize, lineOpen, lineSetStatusMessages, lineShutdown, LINETRANSLATECAPS, lineUncompleteCall


LINE_MONITORDIGITS

The LINE_MONITORDIGITS message is sent when a digit is detected. The sending of this message is controlled with the lineMonitorDigits function.

LINE_MONITORDIGITS
dwDevice = (DWORD) hCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) Digit;
dwParam2 = (DWORD) DigitMode;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
A handle to the call.
dwCallbackInstance
The callback instance supplied when opening the call's line.
dwParam1
The low-order byte contains the last digit received in ASCII.
dwParam2
The digit mode that was detected. This parameter must be one and only one of the following LINEDIGITMODE_ constants:
LINEDIGITMODE_PULSE
Detect digits as audible clicks that are the result of rotary pulse sequences. Valid digits for pulse are '0' through '9'.
LINEDIGITMODE_DTMF
Detect digits as DTMF tones. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.
LINEDIGITMODE_DTMFEND
Detect and provide application notification of DTMF down edges. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.
dwParam3
The "tick count" (number of milliseconds since Windows started) at which the specified digit was detected. For API versions earlier than 2.0, this parameter is unused.

Return Values

No return value.

Remarks

The LINE_MONITORDIGITS message is sent to the application that has enabled digit monitoring.

Because this timestamp may have been generated on a computer other than the one on which the application is executing, it is useful only for comparison to other similarly timestamped messages generated on the same line device (LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORMEDIA, LINE_MONITORTONE), in order to determine their relative timing (separation between events). The tick count can "wrap around" after approximately 49.7 days; applications must take this into account when performing calculations.

If the service provider does not generate the timestamp (for example, if it was created using an earlier version of TAPI), then TAPI provides a timestamp at the point closest to the service provider generating the event so that the synthesized timestamp is as accurate as possible.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORMEDIA, LINE_MONITORTONE, lineMonitorDigits


LINE_MONITORMEDIA

The LINE_MONITORMEDIA message is sent when a change in the call's media mode is detected. The sending of this message is controlled with the lineMonitorMedia function.

LINE_MONITORMEDIA
dwDevice = (DWORD) hCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) MediaMode;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
A handle to the call.
dwCallbackInstance
The callback instance supplied when opening the line.
dwParam1
The new media mode. This parameter must be one and only one of the following LINEMEDIAMODE_ constants:
LINEMEDIAMODE_INTERACTIVEVOICE
The presence of voice energy has been detected and the call is treated as an interactive call with humans on both ends.
LINEMEDIAMODE_AUTOMATEDVOICE
The presence of voice energy has been detected and the call is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM
A data modem session has been detected.
LINEMEDIAMODE_G3FAX
A group 3 fax has been detected.
LINEMEDIAMODE_G4FAX
A group 4 fax has been detected.
LINEMEDIAMODE_TDD
A TDD (Telephony Devices for the Deaf) session has been detected.
LINEMEDIAMODE_DIGITALDATA
Digital data has been detected.
LINEMEDIAMODE_TELETEX
A teletex session has been detected. Teletex is one of the telematic services.
LINEMEDIAMODE_VIDEOTEX
A videotex session has been detected. Videotex is one the telematic services.
LINEMEDIAMODE_TELEX
A telex session has been detected. Telex is one the telematic services.
LINEMEDIAMODE_MIXED
A mixed session has been detected. Mixed is one the telematic services.
LINEMEDIAMODE_ADSI
An ADSI (Analog Display Services Interface) session has been detected.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.
dwParam2
Unused.
dwParam3
The "tick count" (number of milliseconds since Windows started) at which the specified media was detected. For API versions earlier than 2.0, this parameter is unused.

Return Values

No return value.

Remarks

The LINE_MONITORMEDIA message is sent to the application that has enabled media monitoring for the media mode detected.

Because this timestamp may have been generated on a computer other than the one on which the application is executing, it is useful only for comparison to other similarly timestamped messages generated on the same line device (LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORTONE), in order to determine their relative timing (separation between events). The tick count can "wrap around" after approximately 49.7 days; applications must take this into account when performing calculations.

If the service provider does not generate the timestamp (for example, if it was created using an earlier version of TAPI), then TAPI provides a timestamp at the point closest to the service provider generating the event so that the synthesized timestamp is as accurate as possible.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORTONE


LINE_MONITORTONE

The LINE_MONITORTONE message is sent when a tone is detected. The sending of this message is controlled with the lineMonitorTones function.

LINE_MONITORTONE
dwDevice = (DWORD) hCall;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) dwAppSpecific;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
A handle to the call.
dwCallbackInstance
The callback instance supplied when opening the call's line.
dwParam1
The application-specific dwAppSpecific member of the LINEMONITORTONE structure for the tone that was detected.
dwParam2
Unused.
dwParam3
The "tick count" (number of milliseconds since Windows started) at which the tone was detected. For API versions earlier than 2.0, this parameter is unused.

Return Values

No return value.

Remarks

The LINE_MONITORTONE message is only sent to the application that has requested the tone be monitored.

Because this timestamp may have been generated on a computer other than the one on which the application is executing, it is useful only for comparison to other similarly timestamped messages generated on the same line device (LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORTONE), in order to determine their relative timing (separation between events). The tick count can "wrap around" after approximately 49.7 days; applications must take this into account when performing calculations.

If the service provider does not generate the timestamp (for example, if it was created using an earlier version of TAPI), then TAPI provides a timestamp at the point closest to the service provider generating the event so that the synthesized timestamp is as accurate as possible.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINE_GATHERDIGITS, LINE_GENERATE, LINE_MONITORDIGITS, LINE_MONITORTONE, LINEMONITORTONE, lineMonitorTones


LINE_PROXYREQUEST

The LINE_PROXYREQUEST message delivers a request to a registered proxy function handler.

LINE_PROXYREQUEST
dwDevice = (DWORD) hLine;
dwCallbackInstance = (DWORD) dwInstanceData;
dwParam1 = (DWORD) lpProxyRequest;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
The application's handle to the line device on which the agent status has changed.
dwCallbackInstance
The callback instance supplied when opening the call's line.
dwParam1
Pointer to a LINEPROXYREQUEST structure containing the request to be processed by the proxy handler application.
dwParam2
Reserved.
dwParam3
Reserved.

Return Values

No return value.

Remarks

The LINE_PROXYREQUEST message is sent only to the first application that registered to handle proxy requests of the type being delivered.

The application should process the request contained in the proxy buffer and call lineProxyResponse to return data or deliver results. Processing of the request should be done within the context of the application's TAPI callback function only if it can be performed immediately, without waiting for response from any other entity. If the application needs to communicate with other entities (for example, a service provider to handle PBX-based ACD, or any other system service which might result in blocking), then the request should be queued within the application and the callback function exited to avoid delaying the receipt of further TAPI messages by the application.

At the time the LINE_PROXYREQUEST is delivered to the proxy handler, TAPI has already returned a positive dwRequestID function result to the original application and unblocked the calling thread to continue execution. The application is awaiting a LINE_REPLY message, which is automatically generated when the proxy handler application calls lineProxyResponse.

The application shall not free the memory pointed to by lpProxyRequest. TAPI frees the memory during the execution of lineProxyResponse. The application can call lineProxyResponse exactly once for each LINE_PROXYREQUEST message.

If the application receives a LINE_CLOSE message while it has pending proxy requests, it should call lineProxyResponse for each pending request, passing in an appropriate dwResult value (such as LINEERR_OPERATIONFAILED).

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.

See Also

LINE_CLOSE, LINE_REPLY, LINEPROXYREQUEST, lineProxyResponse


LINE_REMOVE

The LINE_REMOVE message is sent to inform an application of the removal (deletion from the system) of a line device. Generally, this is not used for temporary removals, such as extraction of PCMCIA devices, but only for permanent removals in which the device would no longer be reported by the service provider if TAPI were reinitialized.

LINE_REMOVE
dwDevice = (DWORD) 0;
dwCallbackInstance = (DWORD) 0;
dwParam1 = (DWORD) dwDeviceID;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
Reserved. Set to zero.
dwCallbackInstance
Reserved. Set to zero.
dwParam1
Identifier of the line device that was removed.
dwParam2
Reserved. Set to zero.
dwParam3
Reserved. Set to zero.

Return Values

No return value.

Comments and Backward Compatibility

Applications supporting TAPI version 2.0 or later are sent a LINE_REMOVE message. This informs them that the device has been removed from the system. The LINE_REMOVE message is preceded by a LINE_CLOSE message on each line handle, if the application had the line open. This message is sent to all applications supporting TAPI version 2.0 or later that have called lineInitializeEx, including those that do not have any line devices open at the time.

Older applications are sent a LINE_LINEDEVSTATE message specifying LINEDEVSTATE_REMOVED, followed by a LINE_CLOSE message. Unlike the LINE_REMOVE message, however, these older applications can receive these messages only if they have the line open when it is removed. If they do not have the line open, their only indication that the device was removed would be receiving a LINEERR_NODEVICE error when they attempt to access the device.

After a device has been removed, any attempt to access the device by its device identifier results in a LINEERR_NODEVICE error. After all TAPI applications have shutdown so that TAPI can restart, and when TAPI is reinitialized, the removed device no longer occupies a device identifier.

Implementation Note It is TAPI that returns this LINEERR_NODEVICE; after a LINE_REMOVE message is received from a service provider; no further calls are made to that service provider using that line device identifier.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.

See Also

LINE_CLOSE, LINE_LINEDEVSTATE, lineInitializeEx


LINE_REPLY

The LINE_REPLY message is sent to report the results of function calls that completed asynchronously.

LINE_REPLY
dwDevice = (DWORD) 0;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) idRequest;
dwParam2 = (DWORD) Status;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
Not used.
dwCallbackInstance
Returns the application's callback instance.
dwParam1
The request identifier for which this is the reply.
dwParam2
The success or error indication. The application should cast this parameter into a LONG. Zero indicates success; a negative number indicates an error.
dwParam3
Unused.

Return Values

No return value.

Remarks

Functions that operate asynchronously return a positive request identifier value to the application. This request identifier is returned with the reply message to identify the request that was completed. The other parameter for the LINE_REPLY message carries the success or failure indication. Possible errors are the same as those defined by the corresponding function. This message cannot be disabled.

In some cases, an application may fail to receive the LINE_REPLY message corresponding to a call to an asynchronous function. This occurs if the corresponding call handle is deallocated before the message has been received.

Note When an application invokes any asynchronous operation that writes data back into application memory, the application must keep that memory available for writing until a LINE_REPLY or LINE_GATHERDIGITS message is received.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

LINE_GATHERDIGITS


LINE_REQUEST

The LINE_REQUEST message is sent to report the arrival of a new request from another application.

LINE_REQUEST
dwDevice = (DWORD) 0;
dwCallbackInstance = (DWORD) hRegistration;
dwParam1 = (DWORD) RequestMode;
dwParam2 = (DWORD) RequestModeDetail1;
dwParam3 = (DWORD) RequestModeDetail2;

Parameters

dwDevice
Not used.
dwCallbackInstance
The registration instance of the application specified on lineRegisterRequestRecipient.
dwParam1
The request mode of the newly pending request. This parameter uses the following LINEREQUESTMODE_ constants:
LINEREQUESTMODE_MAKECALL
A tapiRequestMakeCall request.
dwParam2
If dwParam1 is set to LINEREQUESTMODE_DROP, dwParam2 contains the hWnd of the application requesting the drop. Otherwise, dwParam2 is unused.
dwParam3
If dwParam1 is set to LINEREQUESTMODE_DROP, the low-order word of dwParam3 contains the wRequestID as specified by the application requesting the drop. Otherwise, dwParam3 is unused.

Return Values

No return value.

Remarks

The LINE_REQUEST message is sent to the highest priority application that has registered for the corresponding request mode. This message indicates the arrival of an Assisted Telephony request of the specified request mode. If dwParam1 is LINEREQUESTMODE_MAKECALL or LINEREQUESTMODE_MEDIACALL, the application can invoke lineGetRequest using the corresponding request mode to receive the request. If dwParam1 is LINEREQUESTMODE_DROP, the message contains all of the information the request recipient needs to perform the request.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

lineGetRequest, lineRegisterRequestRecipient, tapiRequestMakeCall


Phone Device Messages

The following section contains the reference for phone device messages.


PHONE_BUTTON

The PHONE_BUTTON message is sent to notify the application that button press monitoring is enabled if it has detected a button press on the local phone.

PHONE_BUTTON
hPhone = (HPHONE) hPhoneDevice;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) idButtonOrLamp;
dwParam2 = (DWORD) ButtonMode;
dwParam3 = (DWORD) ButtonState;

Parameters

hPhone
A handle to the phone device.
dwCallbackInstance
The application's callback instance provided when opening the phone device.
dwParam1
The button/lamp identifier of the button that was pressed. Note that button identifiers zero through 11 are always the KEYPAD buttons, with '0' being button identifier zero, '1' being button identifier 1 (and so on through button identifier 9), and with '*' being button identifier 10, and '#' being button identifier 11. Additional information about a button identifier is available with phoneGetDevCaps and phoneGetButtonInfo.
dwParam2
The button mode of the button. This parameter uses the following PHONEBUTTONMODE_ constants:
PHONEBUTTONMODE_CALL
The button is assigned to a call appearance.
PHONEBUTTONMODE_FEATURE
The button is assigned to requesting features from the switch, such as hold, conference, and transfer.
PHONEBUTTONMODE_KEYPAD
The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'.
PHONEBUTTONMODE_LOCAL
The button is a local function button, such as mute or volume control.
PHONEBUTTONMODE_DISPLAY
The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.
dwParam3
Specifies whether this is a button-down event or a button-up event. This parameter uses the following PHONEBUTTONSTATE_ constants:
PHONEBUTTONSTATE_UP
The button is in the "up" state.
PHONEBUTTONSTATE_DOWN
The button is in the "down" state (pressed down).
PHONEBUTTONSTATE_UNKNOWN
Indicates that the up or down state of the button is not known at this time, but may become known at a future time.
PHONEBUTTONSTATE_UNAVAIL
Indicates that the up or down state of the button is not known to the service provider, and cannot become known at a future time.

Return Values

No return value.

Remarks

A PHONE_BUTTON message is sent whenever a button changes state. An application is guaranteed that for each button down event, it is eventually sent a corresponding button up event. A service provider that is incapable of detecting the actual button up is required to generate the button up message shortly after the button down message for each button press.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

phoneGetButtonInfo, phoneGetDevCaps


PHONE_CLOSE

The PHONE_CLOSE message is sent when an open phone device has been forcibly closed as part of resource reclamation. The device handle is no longer valid once this message has been sent.

PHONE_CLOSE
hPhone = (HPHONE) hPhoneDevice;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) 0;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

hPhone
A handle to the open phone device that was closed. The handle is no longer valid after this message has been sent.
dwCallbackInstance
The application's callback instance that provided when opening the phone device.
dwParam1
Unused.
dwParam2
Unused.
dwParam3
Unused.

Return Values

No return value.

Remarks

The PHONE_CLOSE message is only sent to an application after an open phone has been forcibly closed. This can be done to prevent a single application from monopolizing a phone device for too long. Whether the phone can be reopened immediately after a forced close is device specific.

An open phone device can also be forcibly closed after the user has modified the configuration of that phone or its driver. If the user wants the configuration changes to be effective immediately (as opposed to after the next system restart), and these changes affect the application's current view of the device (such as a change in device capabilities), then a service provider can forcibly close the phone device.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.


PHONE_CREATE

The PHONE_CREATE message is sent to inform applications of the creation of a new phone device.

PHONE_CREATE
hPhone = (HPHONE) hPhoneDev;
dwCallbackInstance = (DWORD) 0;
dwParam1 = (DWORD) idDevice;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

hPhone
Unused.
dwCallbackInstance
Unused.
dwParam1
The dwDeviceID of the newly created device.
dwParam2
Unused.
dwParam3
Unused.

Return Values

No return value.

Remarks

Applications that negotiated API version 1.3 are sent a PHONE_STATE message specifying PHONESTATE_REINIT, which requires them to shut down their use of the API and call phoneInitialize again to obtain the new number of devices. However, TAPI version 1.4 and above do not require all applications to shut down before allowing applications to reinitialize; reinitialization can take place immediately when a new device is created.

Applications supporting TAPI version 1.4 or later are sent a PHONE_CREATE message. This informs them of the existence of the new device and its new device identifier. The application can then choose whether or not to attempt working with the new device at its leisure.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

PHONE_STATE, phoneInitialize, phoneInitializeEx


PHONE_DEVSPECIFIC

The implementation sends the PHONE_DEVSPECIFIC message to an application to notify the application about device-specific events occurring at the phone. The meaning of the message and the interpretation of the parameters is implementation-defined.

PHONE_DEVSPECIFIC
hPhone = (HPHONE) hPhoneDevice;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) DeviceSpecific1;
dwParam2 = (DWORD) DeviceSpecific2;
dwParam3 = (DWORD) DeviceSpecific3;

Parameters

hPhone
A handle to the phone device.
dwCallbackInstance
The application's callback instance provided when opening the phone device.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Return Values

No return value.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.


PHONE_REMOVE

The PHONE_REMOVE message is sent to inform an application of the removal (deletion from the system) of a phone device. Generally, this is not used for temporary removals, such as extraction of PCMCIA devices, but only for permanent removals in which the device would no longer be reported by the service provider if TAPI were reinitialized.

PHONE_REMOVE
dwDevice = (DWORD) 0;
dwCallbackInstance = (DWORD) 0;
dwParam1 = (DWORD) dwDeviceID;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

dwDevice
Reserved. Set to zero.
dwCallbackInstance
Reserved. Set to zero.
dwParam1
Identifier of the phone device that was removed.
dwParam2
Reserved. Set to zero.
dwParam3
Reserved. Set to zero.

Return Values

No return value.

Comments and Backward Compatibility

Applications TAPI version 2.0 or later are sent a PHONE_REMOVE message. This informs them that the device has been removed from the system. The PHONE_REMOVE message is preceded by a PHONE_CLOSE message on each phone handle, if the application had the phone open. This message is sent to all applications supporting TAPI version 2.0 or later that have called phoneInitializeEx, including those that do not have any phone devices open at the time.

Older applications (that negotiated TAPI version 1.4 or earlier) are sent a PHONE_STATE message specifying PHONESTATE_REMOVED, followed by a PHONE_CLOSE message. Unlike the PHONE_REMOVE message, however, these older applications can receive these messages only if they have the phone open when it is removed. If they do not have the phone open, their only indication that the device was removed would be receiving a PHONEERR_NODEVICE when they attempt to access the device.

After a device has been removed, any attempt to access the device by its device identifier results in a PHONEERR_NODEVICE error. After all TAPI applications have shutdown so that TAPI can restart, and when TAPI is reinitialized, the removed device no longer occupies a device identifier.

Implementation Note It is TAPI that returns this PHONEERR_NODEVICE message after a PHONE_REMOVE message is received from a service provider; no further calls are made to that service provider using that phone device identifier.

QuickInfo

Version: Use TAPI version 2.0 and later
Header: Declared in tapi.h.

See Also

PHONE_CLOSE, PHONE_STATE, phoneInitialize, phoneInitializeEx


PHONE_REPLY

The PHONE_REPLY message is sent to an application to report the results of function call that completed asynchronously.

PHONE_REPLY
hPhone = (HPHONE) 0;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) idRequest;
dwParam2 = (DWORD) Status;
dwParam3 = (DWORD) 0;

Parameters

hDevice
Unused.
dwCallbackInstance
Returns the application's callback instance.
dwParam1
The request identifier for which this is the reply.
dwParam2
The success or error indication. The application should cast this parameter into a LONG. Zero indicates success; a negative number indicates an error.
dwParam3
Unused.

Return Values

No return value.

Remarks

Functions that operate asynchronously return a positive request identifier value to the application. This request identifier is returned with the reply message to identify the request that was completed. The other parameter for the PHONE_REPLY message carries the success or failure indication. Possible errors are the same as those defined by the corresponding function. This message cannot be disabled.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.


PHONE_STATE

TAPI sends the PHONE_STATE message to an application whenever the status of a phone device changes.

PHONE_STATE
hPhone = (HPHONE) hPhoneDevice;
dwCallbackInstance = (DWORD) hCallback;
dwParam1 = (DWORD) PhoneState;
dwParam2 = (DWORD) PhoneStateDetails;
dwParam3 = (DWORD) 0;

Parameters

hPhone
A handle to the phone device.
dwCallbackInstance
The application's callback instance provided when opening the phone device.
dwParam1
The phone state that has changed. This parameter uses the following PHONESTATE_ constants:
PHONESTATE_OTHER
Phone-status items other than those listed below have changed. The application should check the current phone status to determine which items have changed.
PHONESTATE_CONNECTED
The connection between the phone device and TAPI was just made. This happens when TAPI is first invoked or when the wire connecting the phone to the computer is plugged in while TAPI is active.
PHONESTATE_DISCONNECTED
The connection between the phone device and TAPI was just broken. This happens when the wire connecting the phone set to the computer is unplugged while TAPI is active.
PHONESTATE_OWNER
The number of owners for the phone device has changed.
PHONESTATE_MONITORS
The number of monitors for the phone device has changed.
PHONESTATE_DISPLAY
The display of the phone has changed.
PHONESTATE_LAMP
A lamp of the phone has changed.
PHONESTATE_RINGMODE
The ring mode of the phone has changed.
PHONESTATE_RINGVOLUME
The ring volume of the phone has changed.
PHONESTATE_HANDSETHOOKSWITCH
The handset hookswitch state has changed.
PHONESTATE_HANDSETVOLUME
The handset's speaker volume setting has changed.
PHONESTATE_HANDSETGAIN
The handset's microphone gain setting has changed.
PHONESTATE_SPEAKERHOOKSWITCH
The speakerphone's hookswitch state has changed.
PHONESTATE_SPEAKERVOLUME
The speakerphone's speaker volume setting has changed.
PHONESTATE_SPEAKERGAIN
The speakerphone's microphone gain setting state has changed.
PHONESTATE_HEADSETHOOKSWITCH
The headset's hookswitch state has changed.
PHONESTATE_HEADSETVOLUME
The headset's speaker volume setting has changed.
PHONESTATE_HEADSETGAIN
The headset's microphone gain setting has changed.
PHONESTATE_SUSPEND
The application's use of the phone device is temporarily suspended.
PHONESTATE_RESUME
The application's use of the phone device is resumed after having been suspended for some time.
PHONESTATE_DEVSPECIFIC
The phone's device-specific information has changed.
PHONESTATE_REINIT
Items have changed in the configuration of phone devices. To become aware of these changes (as with the appearance of new phone devices), the application should reinitialize its use of TAPI. The hDevice parameter of the PHONE_STATE message is left NULL for this state change as it applies to any of the phones in the system.
PHONESTATE_CAPSCHANGE
Indicates that due to configuration changes made by the user or other circumstances one or more of the members in the PHONECAPS structure have changed. The application should use phoneGetDevCaps to read the updated structure.
PHONESTATE_REMOVED
Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). Normally, a PHONE_STATE message with this value is immediately followed by a PHONE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized result in PHONEERR_NODEVICE being returned to the application. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version do not receive any notification.
dwParam2
Phone state-dependent information detailing the status change. This parameter is not used if multiple flags are set in dwParam1, because multiple status items have changed. The application should invoke phoneGetStatus to obtain a complete set of information.

If dwParam1 is PHONESTATE_OWNER, dwParam2 contains the new number of owners.

If dwParam1 is PHONESTATE_MONITORS, dwParam2 contains the new number of monitors.

If dwParam1 is PHONESTATE_LAMP, dwParam2 contains the button/lamp identifier of the lamp that has changed.

If dwParam1 is PHONESTATE_RINGMODE, dwParam2 contains the new ring mode.

If dwParam1 is PHONESTATE_HANDSET, SPEAKER or HEADSET, dwParam2 contains the new hookswitch mode of that hookswitch device. This parameter uses the following PHONEHOOKSWITCHMODE_ constants:

PHONEHOOKSWITCHMODE_ONHOOK
The device's microphone and speaker are both onhook.
PHONEHOOKSWITCHMODE_MIC
The device's microphone is active, the speaker is mute.
PHONEHOOKSWITCHMODE_SPEAKER
The device's speaker is active, the microphone is mute.
PHONEHOOKSWITCHMODE_MICSPEAKER
The device's microphone and speaker are both active.
dwParam3
Unused.

Return Values

No return value.

Remarks

Sending the PHONE_STATE message to the application can be controlled and queried using phoneSetStatusMessages and phoneGetStatusMessages. By default, this message is disabled for all state changes except for PHONESTATE_REINIT, which cannot be disabled. This message is sent to all applications that have a handle to the phone, including those that called phoneOpen with the dwPrivileges parameter set to PHONEPRIVILEGE_OWNER or PHONEPRIVILEGE_MONITOR.

A PHONE_STATE message with an Owners and/or Monitors indication is sent to applications that already have a handle for the phone. This can be the result of another application changing ownership or monitorship of the phone device with phoneOpen, phoneClose or phoneShutdown.

QuickInfo

Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.

See Also

PHONE_CLOSE, PHONECAPS, phoneClose, phoneGetDevCaps, phoneGetStatus, phoneGetStatusMessages, phoneInitialize, phoneInitializeEx, phoneOpen, phoneSetStatusMessages, phoneShutdown


Formatted Error Messages

The following formatted error message is used with TAPI.

TAPIERROR_FORMATMESSAGE


TAPIERROR_FORMATMESSAGE

The TAPIERROR_FORMATMESSAGE macro generates an identifier for standard TAPI error message text strings that can be obtained by Win32 applications using the Win32 FormatMessage function.

This mechanism should be used only for displaying information on errors for which the application has no defined method of recovery (that is, unexpected or internal errors). In most cases (unlike the following simplified example), it is desirable to include additional text informing the user of actions the application takes (or the user should take) as a result of the unhandled error.

If the application gets an error result from any TAPI function, the error value can be passed through the TAPIERROR_FORMATMESSAGE macro, which in turn generates the real value to be passed to FormatMessage. FormatMessage produces an error string corresponding to the error in a buffer. For example:

lResult = lineClose(hLine);

if (lResult < 0)
{
        FormatMessage(FORMAT_MESSAGE_FROM_HMODULE,
                    (LPCVOID)GetModuleHandle("TAPI32.DLL"),
                    TAPIERROR_FORMATMESSAGE(lResult),
                    0,
                    (LPTSTR)pBuf,
                    BUFSIZE,
                    NULL);
        MessageBox(hWnd,pBuf,"TAPI ERROR",MB_OK);
}


Assisted Telephony Messages

The following message is associated with Assisted Telephony.

TAPI_REPLY


TAPI_REPLY

The TAPI_REPLY message is nonfunctional in Win32-based applications and obsolete for all classes of Windows-based applications. It should not be used.


TAPI Constants

This section contains the reference for the following TAPI constants:

Line Device Constants

Phone Device Constants

Assisted Telephony Constants


Line Device Constants

This section contains an alphabetic listing of the line device constants used by TAPI.


LINEADDRCAPFLAGS_ Constants

The LINEADDRCAPFLAGS_ bit-flag constants are used in the dwAddrCapFlags member of the LINEADDRESSCAPS data structure to describe various Boolean address capabilities.

LINEADDRCAPFLAGS_FWDNUMRINGS
Specifies whether the number of rings for a no-answer can be specified when forwarding calls on no answer. If TRUE, the valid range is provided in LINEADDRESSCAPS.
LINEADDRCAPFLAGS_PICKUPGROUPID
Specifies whether a group identifier is required for call pickup.
LINEADDRCAPFLAGS_SECURE
Specifies whether calls on this address can be made secure at call-setup time.
LINEADDRCAPFLAGS_BLOCKIDDEFAULT
Specifies whether the network by default sends or blocks caller ID information when making a call on this address. If TRUE, identifier information is blocked by default; if FALSE, identifier information is transmitted by default.
LINEADDRCAPFLAGS_BLOCKIDOVERRIDE
Specifies whether the default setting for sending or blocking of caller ID information can be overridden per call. If TRUE, override is possible; if FALSE, override is not possible.
LINEADDRCAPFLAGS_DIALED
Specifies whether a destination address can be dialed on this address for making a call. TRUE if a destination address must be dialed; FALSE if the destination address is fixed (as with a "hot phone").
LINEADDRCAPFLAGS_ORIGOFFHOOK
Specifies whether the originating party's phone can automatically be taken offhook when making calls.
LINEADDRCAPFLAGS_DESTOFFHOOK
Specifies whether the called party's phone can automatically be forced offhook when making calls.
LINEADDRCAPFLAGS_FWDCONSULT
Specifies whether call forwarding involves the establishment of a consultation call.
LINEADDRCAPFLAGS_SETUPCONFNULL
Specifies whether setting up a conference call starts out with an initial call (FALSE) or with no initial call (TRUE).
LINEADDRCAPFLAGS_AUTORECONNECT
Specifies whether dropping a consultation call automatically reconnects to the call on consultation hold. TRUE if reconnect happens automatically; otherwise, FALSE.
LINEADDRCAPFLAGS_COMPLETIONID
Specifies whether the completion identifiers returned by lineCompleteCall are useful and unique. TRUE if useful; otherwise, FALSE.
LINEADDRCAPFLAGS_TRANSFERHELD
Specifies whether a hard-held call can be transferred. Often, only calls on consultation hold can be transferred.
LINEADDRCAPFLAGS_TRANSFERMAKE
Specifies whether an entirely new call can be established for use as a consultation call on transfer.
LINEADDRCAPFLAGS_CONFERENCEHELD
Specifies whether a hard-held call can be conferenced to. Often, only calls on consultation hold can be added to as a conference call.
LINEADDRCAPFLAGS_CONFERENCEMAKE
Specifies whether an entirely new call can be established for use as a consultation call (to add) on conference.
LINEADDRCAPFLAGS_PARTIALDIAL
Specifies whether partial dialing is available.
LINEADDRCAPFLAGS_FWDSTATUSVALID
Specifies whether the forwarding status in the LINEADDRESSSTATUS structure for this address is valid or is at most a "best estimate," given absence of accurate confirmation by the switch or network.
LINEADDRCAPFLAGS_FWDINTEXTADDR
Specifies whether internal and external calls can be forwarded to different forwarding addresses. This flag is meaningful only if forwarding of internal and external calls can be controlled separately. This flag is TRUE if internal and external calls can be forwarded to different destination addresses; otherwise, it is FALSE.
LINEADDRCAPFLAGS_FWDBUSYNAADDR
Specifies whether call forwarding for busy and for no answer can use different forwarding addresses. This flag is meaningful only if forwarding for busy and for no answer can be controlled separately. This flag is TRUE if forwarding for busy and for no answer can use different destination addresses; otherwise, it is FALSE.
LINEADDRCAPFLAGS_ACCEPTTOALERT
TRUE if an offering call must be accepted using lineAccept to start alerting the users at both ends of the call; otherwise, FALSE. This is typically only used with ISDN.
LINEADDRCAPFLAGS_CONFDROP
TRUE if lineDrop on a conference call parent also has the side effect of dropping (that is, disconnecting) the other parties involved in the conference call; FALSE if dropping a conference call still allows the other parties to talk among themselves.
LINEADDRCAPFLAGS_PICKUPCALLWAIT
TRUE if linePickup can be used to pick up a call detected by the user as a call-waiting call; otherwise, FALSE.
LINEADDRCAPFLAGS_PREDICTIVEDIALER
This address has enhanced call progress monitoring capabilities which can be applied to outgoing calls to determine call states such as ringback, busy, specialinfo, and connected, or the media mode of the device answering the call. It may also have the ability to automatically transfer outgoing calls to another address when a call reaches any of a predefined set of states.
LINEADDRCAPFLAGS_QUEUE
This address is not associated with a particular station or physical device, but is a holding place where calls wait for further processing. The calls placed in the queue may receive a particular treatment. They may also be automatically transferred when a particular resource becomes available (for example, if the queue is an ACD queue and calls are waiting for an available agent).
LINEADDRCAPFLAGS_ROUTEPOINT
This address is not associated with a particular station or physical device, but is a holding place where calls wait for routing by the application (the application examines the called address, and can redirect the call to another address). The call can also be automatically transferred if a routing timeout expires (the switch usually assumes a default routing).
LINEADDRCAPFLAGS_HOLDMAKESNEW
When a call on this address is placed on hold (using lineHold or external action), a new call is automatically created (most likely in LINECALLSTATE_DIALTONE).
LINEADDRCAPFLAGS_NOINTERNALCALLS
The address is associated with a direct CO line (trunk), and cannot be used to make internal calls on a PBX. The application can use this indication to assist the user in selecting the correct call appearance to use for making a call. When this bit is off, it does not necessarily indicate that the address can be used to make internal calls, because the service provider may not be cognizant of the line type.
LINEADDRCAPFLAGS_NOEXTERNALCALLS
The address is associated with an internal line on a PBX that is restricted in such a way that it cannot be used to place calls to an address outside the switch (for example, it is an intercom). The application can use this indication to assist the user in selecting the correct call appearance to use for making a call. When this bit is off, it does not necessarily indicate that the address can be used to make external calls, because the service provider may not be cognizant of the line type.
LINEADDRCAPFLAGS_SETCALLINGID
The application can choose to set the CallingPartyID member in LINECALLPARAMS when calling lineMakeCall and other functions that accept a LINECALLPARAMS structure. The service provider will, if the content of the identifier is acceptable and a path is available, pass the identifier along to the called party to indicate the identity of the calling party.

No extensibility. All 32 bits are reserved.

See Also

lineAccept, LINEADDRESSCAPS, LINEADDRESSSTATUS, LINECALLPARAMS, lineCompleteCall, lineDrop, lineHold, lineMakeCall, linePickup


LINEADDRESSMODE_ Constants

The LINEADDRESSMODE_ bit-flag constants describe various ways of identifying an address on a line device.

LINEADDRESSMODE_ADDRESSID
The address is specified with a small integer in the range 0 to dwNumAddresses minus one, where dwNumAddresses is the value in the line's device capabilities.
LINEADDRESSMODE_DIALABLEADDR
The address is specified through its phone number.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

This constant is used to select an address on a line on which to originate a call. The usual model would select the address by means of its address identifier. Address identifiers are the mechanism used to identify addresses throughout TAPI. However, in some environments, when making a call, it is often more practical to identify a call's originating address by phone number rather than by address identifier. One example is in the possible modeling of large numbers of stations (third party) on the switch by means of one line device with many addresses. The line represents the set of all stations, and each station is mapped to an address with its own primary phone number and address identifier.


LINEADDRESSSHARING_ Constants

The LINEADDRESSSHARING_ bit-flag constants describe various ways an address can be shared between lines.

LINEADDRESSSHARING_PRIVATE
The address is private to the user's line; it is not assigned to any other station.
LINEADDRESSSHARING_BRIDGEDEXCL
The address is bridged to one or more other stations. The first line to activate a call on the line will have exclusive access to the address and calls that may exist on it. Other lines will not be able to use the bridged address while it is in use.
LINEADDRESSSHARING_BRIDGEDNEW
The address is bridged with one or more other stations. The first line to activate a call on the line will have exclusive access to only the corresponding call. Other applications that use the address will result in new and separate call appearances.
LINEADDRESSSHARING_BRIDGEDSHARED
The address is bridged with one or more other lines. All bridged parties can share in calls on the address, which then functions as a conference.
LINEADDRESSSHARING_MONITORED
This is an address whose idle/busy status is made available to this line.

No extensibility. All 32 bits are reserved.

The way in which an address is shared across lines can affect the behavior of that address. LINE_CALLSTATE and LINE_ADDRESSSTATE messages are sent to the application in response to activities by the bridging stations. It is through these messages that an application can track the status of the address.

See Also

LINE_ADDRESSSTATE, LINE_CALLSTATE


LINEADDRESSSTATE_ Constants

The LINEADDRESSSTATE_ bit-flag constants describe various address status items.

LINEADDRESSSTATE_OTHER
Address-status items other than those listed below have changed. The application should check the current address status to determine which items have changed.
LINEADDRESSSTATE_DEVSPECIFIC
The device-specific item of the address status has changed.
LINEADDRESSSTATE_INUSEZERO
The address has changed to idle (it is not in use by any stations).
LINEADDRESSSTATE_INUSEONE
The address has changed from idle or in use by many bridged stations to being in use by just one station.
LINEADDRESSSTATE_INUSEMANY
The monitored or bridged address has changed from being in use by one station to being in use by more than one station.
LINEADDRESSSTATE_NUMCALLS
The number of calls on the address has changed. This is the result of events such as a new incoming call, an outgoing call on the address, or a call changing its hold status. This flag covers changes in any of the members dwNumActiveCalls, dwNumOnHoldCalls and dwNumOnHoldPendingCalls in the LINEADDRESSSTATUS structure. The application should check all three of these members when it receives a LINE_ADDRESSSTATE (numCalls) message.
LINEADDRESSSTATE_FORWARD
The forwarding status of the address has changed, including possibly the number of rings for determining a no-answer condition. The application should check the address status to determine details about the address's current forwarding status.
LINEADDRESSSTATE_TERMINALS
The terminal settings for the address have changed.
LINEADDRESSSTATE_CAPSCHANGE
Indicates that, due to configuration changes made by the user or other circumstances, one or more of the members in the LINEADDRESSCAPS structure for the address have changed. The application should use lineGetAddressCaps to read the updated structure. If a service provider sends a LINE_ADDRESSSTATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated TAPI version 1.4 or later; applications negotiating a previous API version will receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI to obtain the updated information.

No extensibility. All 32 bits are reserved.

An application is notified about changes to these status items in the LINE_ADDRESSSTATE message. The address's device capabilities indicate which address state changes can possibly be reported for this address.

See Also

LINE_ADDRESSSTATE, LINE_LINEDEVSTATE, LINEADDRESSCAPS, LINEADDRESSSTATUS, lineGetAddressCaps


LINEADDRFEATURE_ Constants

The LINEADDRFEATURE_ constants list the operations that can be invoked on an address.

LINEADDRFEATURE_FORWARD
The address can be forwarded.
LINEADDRFEATURE_MAKECALL
An outgoing call can be placed on the address.
LINEADDRFEATURE_PICKUP
A call can be picked up at the address.
LINEADDRFEATURE_SETMEDIACONTROL
Media control can be set on this address.
LINEADDRFEATURE_SETTERMINAL
The terminal modes for this address can be set.
LINEADDRFEATURE_SETUPCONF
A conference call with a NULL initial call can be set up at this address.
LINEADDRFEATURE_UNCOMPLETECALL
Call completion requests can be canceled at this address.
LINEADDRFEATURE_UNPARK
Calls can be unparked using this address.
LINEADDRFEATURE_PICKUPHELD
The linePickup function (with a null destination address) can be used to pick up a call that is held on the address. This is normally used only in a bridged-exclusive arrangement.
LINEADDRFEATURE_PICKUPGROUP
The linePickup function can be used to pick up a call in the group.
LINEADDRFEATURE_PICKUPDIRECT
The linePickup function can be used to pick up a call on a specific address.
LINEADDRFEATURE_PICKUPWAITING
The linePickup function (with a null destination address) can be used to pick up a call waiting call. Note that this does not necessarily indicate that a waiting call is actually present, because it is often impossible for a telephony device to automatically detect such a call; it does, however, indicate that the hook-flash function will be invoked to attempt to switch to such a call.

Note If none of the new modified "PICKUP" bits is set in the dwAddressFeatures member in LINEADDRESSSTATUS but the LINEADDRFEATURE_PICKUP bit is set, then any of the pickup modes may work; the service provider has simply not specified which ones.

LINEADDRFEATURE_FORWARDFWD
The lineForward function can be used to forward calls on the address to other numbers. LINEADDRFEATURE_FORWARD will also be set.
LINEADDRFEATURE_FORWARDDND
The lineForward function (with an empty destination address) can be used to turn on the Do Not Disturb feature on the address. LINEADDRFEATURE_FORWARD will also be set.

Note If neither of the new modified "FORWARD" bits is set in the dwAddressFeatures member in LINEADDRESSSTATUS but the LINEADDRFEATURE_FORWARD bit is set, then any of the forward modes may work; the service provider has simply not specified which ones.

No extensibility. All 32 bits are reserved.

This constant is used both in LINEADDRESSCAPS (returned by lineGetAddressCaps) and in LINEADDRESSSTATUS (returned by lineGetAddressStatus). LINEADDRESSCAPS reports the availability of the address features by the service provider (mainly the switch) for a given address. An application would make this determination when it initializes. The LINEADDRESSSTATUS structure reports, for a given address, which address features can actually be invoked while the address is in the current state. An application would make this determination dynamically after address-state changes, typically caused by call-related activities on the address.

See Also

LINEADDRESSCAPS, LINEADDRESSSTATUS, lineForward, lineGetAddressCaps, lineGetAddressStatus, linePickup


LINEAGENTFEATURE_ Constants

The LINEAGENTFEATURE_ constants list features that are available for an agent on an address.

LINEAGENTFEATURE_SETAGENTGROUP
The lineSetAgentGroup function can be invoked on this address.
LINEAGENTFEATURE_SETAGENTSTATE
The lineSetAgentState function can be invoked on this address.
LINEAGENTFEATURE_SETAGENTACTIVITY
The lineSetAgentActivity function can be invoked on this address.
LINEAGENTFEATURE_AGENTSPECIFIC
The lineAgentSpecific function can be invoked on this address.
LINEAGENTFEATURE_GETAGENTACTIVITYLIST
The lineGetAgentActivityList function can be invoked on this address.
LINEAGENTFEATURE_GETAGENTGROUPLIST
The lineGetAgentGroupList function can be invoked on this address.


LINEAGENTSTATE_ Constants

The LINEAGENTSTATE_ constants list the state of an agent on an address.

LINEAGENTSTATE_LOGGEDOFF
No agent is logged in on the address.
LINEAGENTSTATE_NOTREADY
The agent is logged in, but occupied with a task other than serving a call (such as on a break). No additional calls should be routed to the agent.
LINEAGENTSTATE_READY
The agent is ready to accept calls.
LINEAGENTSTATE_BUSYACD
The agent is busy handling a call routed from an ACD queue.
LINEAGENTSTATE_BUSYINCOMING
The agent is busy handling an incoming call that was not transferred to the agent from an ACD queue in which the agent is logged in.
LINEAGENTSTATE_BUSYOUTBOUND
The agent is busy handling an outgoing call, such as one routed from a predictive dialing queue.
LINEAGENTSTATE_BUSYOTHER
The agent is busy handling another type of call, such as an outgoing personal call not transferred to the agent by a predictive dialer. This value can also be used when the agent is known to be busy on a call but the type of call is unknown.
LINEAGENTSTATE_WORKINGAFTERCALL
The agent has completed the preceding call, but is still occupied with work related to that call. The agent should not receive additional calls.
LINEAGENTSTATE_UNKNOWN
The agent state is currently unknown, but may become known later. This can be a transitional state when a line or address is first opened.
LINEAGENTSTATE_UNAVAIL
The agent state is unknown and will never become known. In LINEADDRESSSTATUS, this condition can also be represented by the dwAgentState member being set to 0.

The upper 16-bits of this set of constants are reserved for device-specific extensions.


LINEAGENTSTATUS_ Constants

The LINEAGENTSTATUS_ constants list the update status of the members of the LINEAGENTSTATUS for an agent.

LINEAGENTSTATE_GROUP
The Group List in LINEAGENTSTATUS has been updated.
LINEAGENTSTATE_STATE
The dwState member in LINEAGENTSTATUS has been updated.
LINEAGENTSTATE_NEXTSTATE
The dwNextState member in LINEAGENTSTATUS has been updated.
LINEAGENTSTATE_ACTIVITY
The ActivityID, ActivitySize, or ActivityOffset members in LINEAGENTSTATUS has been updated.
LINEAGENTSTATE_ACTIVITYLIST
The List member in LINEAGENTACTIVITYLIST has been updated. The application can call lineGetAgentActivityList to get the updated list.
LINEAGENTSTATE_GROUPLIST
The List member in LINEAGENTGROUPLIST has been updated. The application can call lineGetAgentGroupList to get the updated list.
LINEAGENTSTATE_CAPSCHANGE
The capabilities in LINEAGENTCAPS have been updated. The application can call lineGetAgentCaps to get the updated list.
LINEAGENTSTATE_VALIDSTATES
The dwValidStates member in LINEAGENTSTATUS has been updated.
LINEAGENTSTATE_VALIDNEXTSTATES
The dwValidNextStates member in LINEAGENTSTATUS has been updated.

See Also

LINEAGENTACTIVITYLIST, LINEAGENTCAPS, LINEAGENTGROUPLIST, LINEAGENTSTATUS, lineGetAgentActivityList, lineGetAgentCaps, lineGetAgentGroupList


LINEANSWERMODE_ Constants

The LINEANSWERMODE_ bit-flag constants describe how an existing active call on a line device is affected by answering another offering call on the same line.

LINEANSWERMODE_NONE
Answering another call on the same line has no effect on the existing active call on the line.
LINEANSWERMODE_DROP
The currently active call will automatically be dropped.
LINEANSWERMODE_HOLD
The currently active call will automatically be placed on hold.

No extensibility. All 32 bits are reserved.

If a call comes in (is offered) at the time another call is already active, the new call is connected to by invoking lineAnswer. The effect this has on the existing active call depends on the line's device capabilities. The first call may be unaffected, it may automatically be dropped, or it may automatically be placed on hold.


LINEBEARERMODE_ Constants

The LINEBEARERMODE_ bit-flag constants describe different bearer modes of a call. When an application makes a call, it can request a specific bearer mode. These modes are used to select a certain quality of service for the requested connection from the underlying telephone network. Bearer modes available on a given line are a device capability of the line.

LINEBEARERMODE_VOICE
This is a regular 3.1 kHz analog voice-grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.
LINEBEARERMODE_SPEECH
This corresponds to G.711 speech transmission on the call. The network can use processing techniques such as analog transmission, echo cancellation, and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.
LINEBEARERMODE_MULTIUSE
The multiuse mode defined by ISDN.
LINEBEARERMODE_DATA
The unrestricted data transfer on the call. The data rate is specified separately.
LINEBEARERMODE_ALTSPEECHDATA
The alternate transfer of speech or unrestricted data on the same call (ISDN).
LINEBEARERMODE_NONCALLSIGNALING
This corresponds to a non-call-associated signaling connection from the application to the service provider or switch (treated as a media stream by TAPI).
LINEBEARERMODE_PASSTHROUGH
When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 comm functions, for the purpose of configuring or using special features not otherwise supported by the service provider.
LINEBEARERMODE_RESTRICTEDDATA
Bearer service for digital data in which only the low-order seven bits of each octet may contain user data (for example, for Switched 56kbit/s service).

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Note that bearer mode and media mode are different notions. The bearer mode of a call is an indication of the quality of the telephone connection as provided primarily by the network. The media mode of a call is an indication of the type of information stream that is exchanged over that call. Group 3 fax or data modem are media modes that use a call with a 3.1 kHz voice bearer mode.


LINEBUSYMODE_ Constants

The LINEBUSYMODE_ bit-flag constants describe different busy signals that the switch or network can generate. These busy signals typically indicate that a different resource that is required to make a call is currently in use.

LINEBUSYMODE_STATION
The busy signal indicates that the called party's station is busy. This is usually signaled with a normal busy tone.
LINEBUSYMODE_TRUNK
The busy signal indicates that a trunk or circuit is busy. This is usually signaled with a fast busy tone.
LINEBUSYMODE_UNKNOWN
The busy signal's specific mode is currently unknown but may become known later.
LINEBUSYMODE_UNAVAIL
The busy signal's specific mode is unavailable and will not become known.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Note Busy signals can be sent as inband tones or out-of-band messages. TAPI makes no assumption about the specific signaling mechanism.


LINECALLCOMPLCOND_ Constants

The LINECALLCOMPLCOND_ bit-flag constants describe the conditions under which a call can be completed.

LINECALLCOMPLCOND_BUSY
Completion of the call under busy conditions.
LINECALLCOMPLCOND_NOANSWER
Completion of the call under ringback no answer conditions.

No extensibility. All 32 bits are reserved.


LINECALLCOMPLMODE_ Constants

The LINECALLCOMPLMODE_ bit-flag constants describe different ways in which a call can be completed.

LINECALLCOMPLMODE_CAMPON
Queues the call until the call can be completed.
LINECALLCOMPLMODE_CALLBACK
Requests the called station to return the call when it returns to idle.
LINECALLCOMPLMODE_INTRUDE
Adds the application to the existing call at the called station (barge in).
LINECALLCOMPLMODE_MESSAGE
Leaves a short predefined message for the called station (Leave Word Calling). The message to be sent is specified separately.

No extensibility. All 32 bits are reserved.


LINECALLFEATURE_ Constants

The LINECALLFEATURE_ constants list the operations that can be invoked on a call using this API.

Each of the LINECALLFEATURE_ values correspond to the TAPI operations with the same name. The list is not repeated here.

No extensibility. All 32 bits are reserved.

This constant is used both in LINEADDRESSCAPS (returned by lineGetAddressCaps) and in LINECALLSTATUS (returned by lineGetCallStatus). LINEADDRESSCAPS reports the availability of the call features on the specified address. An application would use this information when it initializes to determine what it may be able to do later when calls exist. For the specified call, LINECALLSTATUS reports which call features can be invoked while the call is in the current call state. The latter takes call privileges into account. An application would make this determination dynamically, after call state changes.

The LINECALLFEATURE_RELEASEUSERUSER value is new. No backward compatibility considerations. A service provider may elect to return this value in relevant members (in LINEADDRESSCAPS and LINECALLSTATUS) even when older API versions have been negotiated on the line device.

The LINECALLFEATURE_SETTREATMENT, LINECALLFEATURE_SETQOS, and LINECALLFEATURE_SETCALLDATA constants are available for API versions 2.0 and later.

See Also

LINEADDRESSCAPS, LINECALLSTATUS, lineGetAddressCaps, lineGetCallStatus


LINECALLFEATURE2_ Constants

The LINECALLFEATURE2_ constants list the supplemental features available for conferencing, transferring, and parking calls.

LINECALLFEATURE2_NOHOLDCONFERENCE
If this bit is on, a "no hold conference" can be created by using the LINECALLPARAMFLAGS_NOHOLDCONFERENCE option with lineSetupConference. The LINECALLFEATURE_SETUPCONF bit will also be on in the dwCallFeatures member.
LINECALLFEATURE2_ONESTEPTRANSFER
If this bit is on, "one step transfer" can be created by using the LINECALLPARAMFLAGS_ONESTEPTRANSFER option with lineSetupTransfer. The LINECALLFEATURE_SETUPTRANSFER bit will also be on in the dwCallFeatures member.
LINECALLFEATURE2_COMPLCAMPON
If this bit is on, the "camp on" feature can be invoked by using the LINECOMPLMODE_CAMPON option with lineCompleteCall. The LINECALLFEATURE_COMPLETECALL bit will also be on in the dwCallFeatures member.
LINECALLFEATURE2_COMPLCALLBACK
If this bit is on, the "callback" feature can be invoked by using the LINECOMPLMODE_CALLBACK option with lineCompleteCall. The LINECALLFEATURE_COMPLETECALL bit will also be on in the dwCallFeatures member.
LINECALLFEATURE2_COMPLINTRUDE
If this bit is on, the "intrude" feature can be invoked by using the LINECOMPLMODE_INTRUDE option with lineCompleteCall. The LINECALLFEATURE_COMPLETECALL bit will also be on in the dwCallFeatures member.
LINECALLFEATURE2_COMPLMESSAGE
If this bit is on, the "leave message" feature can be invoked by using the LINECOMPLMODE_MESSAGE option with lineCompleteCall. The LINECALLFEATURE_COMPLETECALL bit will also be on in the dwCallFeatures member.

Note If none of the "COMPL" bits is specified in the dwCallFeature2 member in LINECALLSTATUS but LINECALLFEATURE_COMPLETECALL is specified, then it is possible that any of them will work, but the service provider has not specified which.

LINECALLFEATURE2_TRANSFERNORM
If this bit is on, the lineCompleteTransfer function can be used to resolve the transfer as a normal transfer. The LINECALLFEATURE_COMPLETETRANSF bit will also be on in the dwCallFeatures member.
LINECALLFEATURE2_TRANSFERCONF
If this bit is on, the lineCompleteTransfer function can be used to resolve the transfer as a three-way conference. The LINECALLFEATURE_COMPLETETRANSF bit will also be on in the dwCallFeatures member.

Note If neither TRANSFERNORM nor TRANSFERCONF is specified in the dwCallFeature2 member in LINECALLSTATUS but LINECALLFEATURE_COMPLETETRANSF is specified, then it is possible that either will work, but the service provider has not specified which.

LINECALLFEATURE2_PARKDIRECT
If this bit is on, the "directed park" feature can be invoked by using the LINEPARKMODE_DIRECTED option with linePark. The LINECALLFEATURE_PARK bit will also be on in the dwCallFeatures member.
LINECALLFEATURE2_PARKNONDIRECT
If this bit is on, the "non-directed park" feature can be invoked by using the LINEPARKMODE_NONDIRECTED option with linePark. The LINECALLFEATURE_PARK bit will also be on in the dwCallFeatures member.

Note If neither PARKDIRECT nor PARKNONDIRECT is specified in the dwCallFeature2 member in LINECALLSTATUS but LINECALLFEATURE_PARK is specified, then it is possible that either will work, but the service provider has not specified which.

See Also

LINECALLSTATUS, lineCompleteCall, lineCompleteTransfer, linePark, lineSetupConference, lineSetupTransfer


LINECALLINFOSTATE_ Constants

The LINECALLINFOSTATE_ bit-flag constants describe various call information items about which an application can be notified in the LINE_CALLINFO message.

LINECALLINFOSTATE_OTHER
Call information items other than those listed below have changed. The application should check the current call information to determine which items have changed.
LINECALLINFOSTATE_DEVSPECIFIC
The device-specific field of the call-information record.
LINECALLINFOSTATE_BEARERMODE
The bearer mode field of the call-information record.
LINECALLINFOSTATE_RATE
The rate field of the call-information record.
LINECALLINFOSTATE_MEDIAMODE
The media-mode field of the call-information record.
LINECALLINFOSTATE_APPSPECIFIC
The application-specific field of the call-information record.
LINECALLINFOSTATE_CALLID
The call ID field of the call-information record.
LINECALLINFOSTATE_RELATEDCALLID
The related call ID field of the call-information record.
LINECALLINFOSTATE_ORIGIN
The origin field of the call-information record.
LINECALLINFOSTATE_REASON
The reason field of the call-information record.
LINECALLINFOSTATE_COMPLETIONID
The completion identifier field of the call-information record.
LINECALLINFOSTATE_NUMOWNERINCR
The number of owner field in the call-information record was increased.
LINECALLINFOSTATE_NUMOWNERDECR
The number of owner field in the call-information record was decreased.
LINECALLINFOSTATE_NUMMONITORS
The number of monitors field in the call-information record has changed.
LINECALLINFOSTATE_TRUNK
The trunk field of the call-information record.
LINECALLINFOSTATE_CALLERID
One of the callerID-related fields of the call-information record.
LINECALLINFOSTATE_CALLEDID
One of the calledID-related fields of the call-information record.
LINECALLINFOSTATE_CONNECTEDID
One of the connectedID-related fields of the call-information record.
LINECALLINFOSTATE_REDIRECTIONID
One of the redirectionID-related fields of the call-information record.
LINECALLINFOSTATE_REDIRECTINGID
One of the redirectingID-related fields of the call-information record.
LINECALLINFOSTATE_DISPLAY
The display field of the call-information record.
LINECALLINFOSTATE_USERUSERINFO
The user-user information of the call-information record.
LINECALLINFOSTATE_HIGHLEVELCOMP
The high level compatibility field of the call-information record.
LINECALLINFOSTATE_LOWLEVELCOMP
The low level compatibility field of the call-information record.
LINECALLINFOSTATE_CHARGINGINFO
The charging information of the call-information record.
LINECALLINFOSTATE_TERMINAL
The terminal mode information of the call-information record.
LINECALLINFOSTATE_DIALPARAMS
The dial parameters of the call-information record.
LINECALLINFOSTATE_MONITORMODES
One or more of the digit, tone, or media monitoring fields in the call-information record.
LINECALLINFOSTATE_TREATMENT
The CallTreatment member in LINECALLINFO has been updated. This can occur in response to a lineSetCallTreatment function, a call state change, a call "vector" or other script controlling the call, or upon completion of playback of a recorded message (ordinarily, indicating a change to "silence" or "music").
LINECALLINFOSTATE_QOS
One or more of the QOS members in LINECALLINFO has been updated.
LINECALLINFOSTATE_CALLDATA
The CallData member in LINECALLINFO has been updated.

No extensibility. All 32 bits are reserved.

When changes occur in this data structure, a LINE_CALLINFO message is sent to the application. The parameters to this message are a handle to the call and an indication of the information item that has changed. The LINEADDRESSCAPS data structure also indicates which of these call information elements are valid for every call on the address.

See Also

LINE_CALLINFO, LINEADDRESSCAPS, LINECALLINFO, lineSetCallTreatment


LINECALLORIGIN_ Constants

The LINECALLORIGIN_ constants describe the origin of a call.

LINECALLORIGIN_OUTBOUND
The call originated from this station as an outgoing call.
LINECALLORIGIN_INTERNAL
The call originated as an incoming call at a station internal to the same switching environment.
LINECALLORIGIN_EXTERNAL
The call originated as an incoming call on an external line.
LINECALLORIGIN_UNKNOWN
The call origin is currently unknown but may become known later.
LINECALLORIGIN_UNAVAIL
The call origin is not available and will never become known for this call.
LINECALLORIGIN_CONFERENCE
The call handle is for a conference call, that is, it is the application's connection to the conference bridge in the switch.
LINECALLORIGIN_INBOUND
The call originated as an incoming call, but the service provider is unable to determine whether it came from another station on the same switch or from an external line.

No extensibility. All 32 bits are reserved.

The origin of a call is stored in the dwOrigin member of the call's LINECALLINFO structure.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use the LINECALLORIGIN_INBOUND value if it is not supported on the negotiated version (LINECALLORIGIN_UNAVAIL may be substituted).


LINECALLPARAMFLAGS_ Constants

The LINECALLPARAMFLAGS_ constants describe various status flags about a call.

LINECALLPARAMFLAGS_SECURE
The call should be set up as secure.
LINECALLPARAMFLAGS_IDLE
The call should be originated on an idle call appearance and not join a call in progress. When using the lineMakeCall function, if the LINECALLPARAMFLAGS_IDLE value is not set and there is an existing call on the line, the function breaks into the existing call if necessary to make the new call. If there is no existing call, the function makes the new call as specified.
LINECALLPARAMFLAGS_BLOCKID
The originator identity should be concealed (block caller ID).
LINECALLPARAMFLAGS_ORIGOFFHOOK
The originator's phone should be automatically taken offhook.
LINECALLPARAMFLAGS_DESTOFFHOOK
The called party's phone should be automatically taken offhook.
LINECALLPARAMFLAGS_NOHOLDCONFERENCE
This bit is used only in conjunction with lineSetupConference and linePrepareAddToConference. The address to be conferenced with the current call is specified in the TargetAddress member in LINECALLPARAMS. The consultation call does not physically draw dial tone from the switch, but will progress through various call establishment states (for example, dialing, proceeding). When the consultation call reaches the connected state, the conference is automatically established; the original call, which had remained in the connected state, enters the conferenced state; the consultation call enters the conferenced state; the hConfCall enters the connected state. If the consultation call fails (enters the disconnected state followed by idle), the hConfCall also enters the idle state, and the original call (which may have been an existing conference, in the case of linePrepareAddToConference) remains in the connected state. The original party (or parties) never perceive the call has having gone onhold. This feature is often used to add a supervisor to an ACD agent call when necessary to monitor interactions with an irate caller.
LINECALLPARAMFLAGS_PREDICTIVEDIAL
This bit is used only when placing a call on an address with predictive dialing capability (LINEADDRCAPFLAGS_PREDICTIVEDIALER is on in the dwAddrCapFlags member in LINEADDRESSCAPS). The bit must be on to enable the enhanced call progress and/or media device monitoring capabilities of the device. If this bit is not on, the call will be placed without enhanced call progress or media mode monitoring, and no automatic transfer will be initiated based on call state.
LINECALLPARAMFLAGS_ONESTEPTRANSFER
This bit is used only in conjunction with lineSetupTransfer. It combines the operation of lineSetupTransfer followed by lineDial on the consultation call into a single step. The address to be dialed is specified in the TargetAddress member in LINECALLPARAMS. The original call is placed in onholdpendingtranfer state, just as if lineSetupTransfer were called normally, and the consultation call is established normally. The application must still call lineCompleteTransfer to effect the transfer. This feature is often used when invoking a transfer from a server over a third-party call control link, because such links frequently do not support the normal two-step process.

No extensibility. All 32 bits are reserved.

See Also

LINEADDRESSCAPS, LINECALLPARAMS, lineCompleteTransfer, lineDial, lineMakeCall, linePrepareAddToConference, lineSetupConference, lineSetupTransfer


LINECALLPARTYID_ Constants

The LINECALLPARTYID_ bit-flag constants describe the nature of the information available about the parties involved in a call.

LINECALLPARTYID_BLOCKED
Party identifier information is not available because it has been blocked by the remote party.
LINECALLPARTYID_OUTOFAREA
Caller ID information for the call is not available since it is not propagated all the way by the network.
LINECALLPARTYID_NAME
Party identifier information consists of the party's name (as, for example, from a directory kept inside the switch).
LINECALLPARTYID_ADDRESS
Party identifier information consists of the party's address in either canonical address format or dialable address format.
LINECALLPARTYID_PARTIAL
Party identifier information is valid but it is limited to partial information only.
LINECALLPARTYID_UNKNOWN
Party identifier information is currently unknown but may become known later.
LINECALLPARTYID_UNAVAIL
Party identifier information is not available and will not become available later. Information may be unavailable for unspecified reasons. For example, the information was not delivered by the network, it was ignored by the service provider, and so forth.

No extensibility. All 32 bits are reserved.

For each of the possible parties involved in a call, the LINECALLPARTYID_ constants describe how the party identifier information is formatted. This information is supplied in the LINECALLINFO data structure.


LINECALLPRIVILEGE_ Constants

The LINECALLPRIVILEGE_ bit-flag constants describe the kinds of access rights or privileges an application with a call handle may have to the corresponding call.

LINECALLPRIVILEGE_NONE
The application has no privileges to the call. The application's handle is void and should not be used.
LINECALLPRIVILEGE_MONITOR
The application has monitor privileges to the call. These privileges allow the application to monitor state changes and query information and status about the call.
LINECALLPRIVILEGE_OWNER
The application has owner privileges to the call. These privileges allow the application to manipulate the call in ways that affect the state of the call.

No extensibility. All 32 bits are reserved.

When a call handle is first provided to an application or whenever call privileges of that application are modified, the LINE_CALLSTATE message is sent to the application. When an application hands off a call, and if the receiving application does not already have a handle with owner privileges, then this message informs the application about its new privileges to the call.


LINECALLREASON_ Constants

The LINECALLREASON_ bit-flag constants describe the reason for a call.

LINECALLREASON_DIRECT
This is a direct incoming or outgoing call.
LINECALLREASON_FWDBUSY
This call was forwarded from another extension that was busy at the time of the call.
LINECALLREASON_FWDNOANSWER
The call was forwarded from another extension that didn't answer the call after some number of rings.
LINECALLREASON_FWDUNCOND
The call was forwarded unconditionally from another number.
LINECALLREASON_PICKUP
The call was picked up from another extension.
LINECALLREASON_UNPARK
The call was retrieved as a parked call.
LINECALLREASON_REDIRECT
The call was redirected to this station.
LINECALLREASON_CALLCOMPLETION
The call was the result of a call completion request.
LINECALLREASON_TRANSFER
The call has been transferred from another number.
LINECALLREASON_REMINDER
The call is a reminder (or "recall") that the user has a call parked or on hold for (potentially) a long time.
LINECALLREASON_UNKNOWN
The reason for the call is currently unknown but may become known later.
LINECALLREASON_UNAVAIL
The reason for the call is unavailable and will not become known later.
LINECALLREASON_INTRUDE
The call intruded onto the line, either by a call completion action invoked by another station or by operator action. Depending on switch implementation, the call may appear either in the connected state, or conferenced with an existing active call on the line.
LINECALLREASON_PARKED
The call was parked on the address. Usually, it appears initially in the onhold state.
LINECALLREASON_CAMPEDON
The call was camped on the address. Usually, it appears initially in the onhold state, and can be switched to using lineSwapHold. If an active call becomes idle, the camped-on call may change to the offering state and the device start ringing.
LINECALLREASON_ROUTEREQUEST
The call appears on the address because the switch needs routing instructions from the application. The application should examine the CalledID member in LINECALLINFO, and use the lineRedirect function to provide a new dialable address for the call. If the call is to be blocked instead, the application may call lineDrop. If the application fails to take action within a switch-defined timeout period, a default action will be taken.

No extensibility. All 32 bits are reserved.

The LINECALLREASON_ constants are used in the dwReason member of the LINECALLINFO data structure.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use these LINECALLREASON_ values if not supported on the negotiated version (LINECALLREASON_UNAVAIL may be substituted).

See Also

LINECALLINFO, lineDrop, lineRedirect, lineSwapHold


LINECALLTREATMENT_ Constants

The LINECALLTREATMENT_ constants lists the manner in which calls of a certain state are treated and the sounds the calling party hears.

LINECALLTREATMENT_BUSY
When the call is not actively connected to a device (offering or onhold), the party hears busy signal.
LINECALLTREATMENT_MUSIC
When the call is not actively connected to a device (offering or onhold), the party hears music.
LINECALLTREATMENT_RINGBACK
When the call is not actively connected to a device (offering or onhold), the party hears ringback tone.
LINECALLTREATMENT_SILENCE
When the call is not actively connected to a device (offering or onhold), the party hears silence.

The value 0x00000000 is reserved to indicate that the service provider does not support call treatments. Values in the range 0x00000005 through 0x000000FF are reserved for future definition. Values in the range 0x00000100 through 0xFFFFFFFF are reserved for assignment by service providers, and may include identification of specific musical selections or recorded announcements.


LINECALLSELECT_ Constants

The LINECALLSELECT_ bit-flag constants describe which calls are to be selected.

LINECALLSELECT_LINE
Selects calls on the specified line device.
LINECALLSELECT_ADDRESS
Selects call on the specified address.
LINECALLSELECT_CALL
Selects related calls to the specified call. For example, the parties in a conference call.

No extensibility. All 32 bits are reserved.

This constant is used in lineGetNewCalls and to specify a selection (scope) of the calls that are requested.


LINECALLSTATE_ Constants

The LINECALLSTATE_ bit-flag constants describe the call states a call can be in.

LINECALLSTATE_IDLE
The call is idle—no call exists.
LINECALLSTATE_OFFERING
The call is being offered to the station, signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user because alerting is done by the switch instructing the line to ring. It does not affect any call states.
LINECALLSTATE_ACCEPTED
The call was offering and has been accepted. This indicates to other (monitoring) applications that the current owner application has claimed responsibility for answering the call. In ISDN, this also initiates alerting to both parties.
LINECALLSTATE_DIALTONE
The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number.
LINECALLSTATE_DIALING
Destination address information (a phone number) is being sent to the switch over the call. Note that lineGenerateDigits does not place the line into the dialing state.
LINECALLSTATE_RINGBACK
The call is receiving ringback from the called address. Ringback indicates that the other station has been reached and is being alerted.
LINECALLSTATE_BUSY
The call is receiving a busy tone. A busy tone indicates that the call cannot be completed—either a circuit (trunk) or the remote party's station are in use.
LINECALLSTATE_SPECIALINFO
Special information is sent by the network. Special information is typically sent when the destination cannot be reached.
LINECALLSTATE_CONNECTED
The call has been established and the connection is made. Information is able to flow over the call between the originating address and the destination address.
LINECALLSTATE_PROCEEDING
Dialing has completed and the call is proceeding through the switch or telephone network.
LINECALLSTATE_ONHOLD
The call is on hold by the switch.
LINECALLSTATE_CONFERENCED
The call is currently a member of a multiparty conference call.
LINECALLSTATE_ONHOLDPENDCONF
The call is currently on hold while it is being added to a conference.
LINECALLSTATE_ONHOLDPENDTRANSFER
The call is currently on hold awaiting transfer to another number.
LINECALLSTATE_DISCONNECTED
The remote party has disconnected from the call.
LINECALLSTATE_UNKNOWN
The state of the call is not known. This may be due to limitations of the call-progress detection implementation.

The high-order 8 bits can define a device-specific substate of any of the predefined states, provided that one of the LINECALLSTATE_ bits defined above is also set. The low-order 24 bits are reserved for predefined states.

The LINECALLSTATE_ constants are used as parameters by the LINE_CALLSTATE message sent to the application. The message carries the new call state that the call transitioned to. These constants are also used as members in the LINECALLSTATUS structure returned by the lineGetCallStatus function.

See Also

LINE_CALLSTATE, LINECALLSTATUS, lineGenerateDigits, lineGetCallStatus


LINECARDOPTION_ Constants

The LINECARDOPTION_ constants define values used in the dwOptions member of the LINECARDENTRY structure returned as part of the LINETRANSLATECAPS structure returned by lineGetTranslateCaps. The LINECARDOPTION_ constant has the following values:

LINECARDOPTION_PREDEFINED
This calling card is one of the predefined calling card definitions included by Microsoft with Win32 Telephony. It cannot be removed entirely using Dial Helper; if the user attempts to remove it, it will become HIDDEN. It thus continues to be accessible for copying of dialing rules.
LINECARDOPTION_HIDDEN
This calling card has been hidden by the user. It is not shown by Dial Helper in the main listing of available calling cards, but will be shown in the list of cards from which dialing rules can be copied.

Not extensible. All 32 bits are reserved.


LINECONNECTEDMODE_ Constants

The LINECONNECTEDMODE_ bit-flag constants describe different substates of a connected call. A mode is available as call status to the application after the call state transitions to connected, and within the LINE_CALLSTATE message indicating the call is in LINECALLSTATE_CONNECTED. These values are used when the call is on an address that is shared (bridged) with other stations (see LINEADDRESSSHARING_ Constants), primarily electronic key systems. The LINECONNECTEDMODE_ constants have the following values:

LINECONNECTEDMODE_ACTIVE
Indicates that the call is connected at the current station (the current station is a participant in the call). If the call state mode is 0 (zero), the application should assume that the value is "active" (which would be the situation on a non-bridged address). The mode can switch between ACTIVE and INACTIVE during a call if the user joins and leaves the call through manual action. In such a bridged situation, a lineDrop or lineHold operation may possibly not actually drop the call or place it on hold, because the status of other stations on the call may govern (for example, attempting to "hold" a call when other stations are participating won't be possible); instead, the call may simply be changed to the INACTIVE mode if it remains CONNECTED at other stations.
LINECONNECTEDMODE_INACTIVE
Indicates that the call is active at one or more other stations, but the current station is not a participant in the call. If the call state mode is ZERO, the application should assume that the value is "active" (which would be the situation on a non-bridged address). A call in the INACTIVE state can be joined using lineAnswer. Many operations that are valid in calls in the CONNECTED state can be impossible in the INACTIVE mode, such as monitoring for tones and digits, because the station is not actually participating in the call; monitoring is usually suspended (although not canceled) while the call is in the INACTIVE mode.
LINECONNECTEDMODE_ACTIVEHELD
Indicates that the station is an active participant in the call, but that the remote party has placed the call on hold (the other party considers the call to be in the onhold state). Normally, such information is available only when both endpoints of the call fall within the same switching domain.
LINECONNECTEDMODE_INACTIVEHELD
Indicates that the station is not an active participant in the call, and that the remote party has placed the call on hold.
LINECONNECTEDMODE_CONFIRMED
Indicates that the service provider received affirmative notification that the call has entered the connected state (for example, through answer supervision or similar mechanisms).

Not extensible. All 32 bits are reserved.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use these LINECONNECTEDMODE_ values if not supported on the negotiated version. It should be noted that applications which are not cognizant of LINECONNECTEDMODE_ will most likely assume that a call that is in LINECALLSTATE_CONNECTED is in LINECONNECTEDMODE_ACTIVE.

The LINECONNECTEDMODE_ACTIVE and LINECONNECTEDMODE_INACTIVE values are used when the call is on an address that is shared with other stations (bridged; see LINEADDRESSSHARING_ Constants), primarily electronic key systems. If the connected call state mode is "active," it means that the call is connected at the current station (the current station is a participant in the call). If the call state mode is "inactive," the call is active at one or more other stations, but the current station is not a participant in the call. If the call state mode is ZERO, the application should assume that the value is "active" (which would be the situation on a non-bridged address). The mode can switch between ACTIVE and INACTIVE during a call if the user joins and leaves the call through manual action.

In such a bridged situation, a lineDrop or lineHold operation may possibly not actually drop the call or place it on hold, because the status of other stations on the call may govern (for example, attempting to "hold" a call when other stations are participating will not be possible); instead, the call can simply be changed to the INACTIVE mode if it remains connected at other stations. A call in the INACTIVE state can be joined using the lineAnswer.

Many operations that are valid in calls in the connected state can be impossible in the INACTIVE mode, such as monitoring for tones and digits, because the station is not actually participating in the call; monitoring is usually suspended (although not canceled) while the call is in the INACTIVE mode.

See Also

lineAnswer, lineDrop, lineHold


LINEDEVCAPFLAGS_ Constants

The LINEDEVCAPFLAGS_ bit-flag constants are a collection of Booleans describing various line device capabilities.

LINEDEVCAPFLAGS_CROSSADDRCONF
Specifies whether calls on different addresses on this line can be conferenced.
LINEDEVCAPFLAGS_HIGHLEVCOMP
Specifies whether high-level compatibility information elements are supported on this line.
LINEDEVCAPFLAGS_LOWLEVCOMP
Specifies whether low-level compatibility information elements are supported on this line.
LINEDEVCAPFLAGS_MEDIACONTROL
Specifies whether media-control operations are available for calls at this line.
LINEDEVCAPFLAGS_MULTIPLEADDR
Specifies whether lineMakeCall or lineDial are able to deal with multiple addresses at once (as for inverse multiplexing).
LINEDEVCAPFLAGS_CLOSEDROP
Specifies what happens when an open line is closed while the application has calls active on the line. If TRUE, the service provider drops (clears) all active calls on the line when the last application that has opened the line closes it with lineClose. If FALSE, the service provider does not drop active calls in such cases. Instead, the calls remain active and under control of external devices. A service provider typically sets this bit to FALSE if there is some other device that can keep the call alive, for example, if an analog line has the computer and phone set both connect directly to them in a party-line configuration, the offhook phone will automatically keep the call active even after the computer powers down.

Applications should check this flag to determine whether to warn the user (with an OK/Cancel dialog box) that active calls will be lost.

LINEDEVCAPFLAGS_DIALBILLING
LINEDEVCAPFLAGS_DIALQUIET
LINEDEVCAPFLAGS_DIALDIALTONE
These flags indicate whether the "$", "@", or "W" dialable string modifier is supported for a given line device. It is TRUE if the modifier is supported; otherwise, FALSE. The "?" (prompt user to continue dialing) is never supported by a line device. These flags allow an application to determine up front which modifiers would result in the generation of a LINEERR. The application has the choice of pre-scanning dialable strings for unsupported characters or of passing the "raw" string from lineTranslateAddress directly to the provider as part of functions such as lineMakeCall or lineDial and let the function generate an error to tell it which unsupported modifier occurs first in the string.

No extensibility. All 32 bits are reserved.

See Also

lineClose, lineDial, lineMakeCall, lineTranslateAddress


LINEDEVSTATE_ Constants

The LINEDEVSTATE_ bit-flag constants describe various line status events.

LINEDEVSTATE_OTHER
Device-status items other than those listed below have changed. The application should check the current device status to determine which items have changed.
LINEDEVSTATE_RINGING
The switch tells the line to alert the user. Service providers notify applications on each ring cycle by sending LINE_LINEDEVSTATE messages containing this constant. For example, in the United States, service providers send a message with this constant every six seconds.
LINEDEVSTATE_CONNECTED
The line was previously disconnected and is now connected to TAPI.
LINEDEVSTATE_DISCONNECTED
This line was previously connected and is now disconnected from TAPI.
LINEDEVSTATE_MSGWAITON
The message waiting indicator is turned on.
LINEDEVSTATE_MSGWAITOFF
The message waiting indicator is turned off.
LINEDEVSTATE_INSERVICE
The line is connected to TAPI. This happens when TAPI is first activated or when the line wire is physically plugged in and in-service at the switch while TAPI is active.
LINEDEVSTATE_OUTOFSERVICE
The line is out of service at the switch or physically disconnected. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_MAINTENANCE
Maintenance is being performed on the line at the switch. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_OPEN
The line has been opened by another application.
LINEDEVSTATE_CLOSE
The line has been closed by another application.
LINEDEVSTATE_NUMCALLS
The number of calls on the line device has changed.
LINEDEVSTATE_NUMCOMPLETIONS
The number of outstanding call completions on the line device has changed.
LINEDEVSTATE_TERMINALS
The terminal settings have changed. This can happen, for example, if multiple line devices share terminals among them (for example, two lines sharing a phone terminal).
LINEDEVSTATE_ROAMMODE
The roam mode of the line device has changed.
LINEDEVSTATE_BATTERY
The battery level has changed significantly (cellular).
LINEDEVSTATE_SIGNAL
The signal level has changed significantly (cellular).
LINEDEVSTATE_DEVSPECIFIC
The line's device-specific information has changed.
LINEDEVSTATE_REINIT
Items have changed in the configuration of line devices. To become aware of these changes (as for the appearance of new line devices) the application should reinitialize its use of TAPI.
LINEDEVSTATE_LOCK
The locked status of the line device has changed. (For more information, see LINEDEVSTATUSFLAGS_LOCKED in LINEDEVSTATUSFLAGS_ Constants.)
LINEDEVSTATE_CAPSCHANGE
Indicates that, due to configuration changes made by the user or other circumstances, one or more of the members in the LINEDEVCAPS structure for the address have changed. The application should use lineGetDevCaps to read the updated structure. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version will receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI to obtain the updated information.
LINEDEVSTATE_CONFIGCHANGE
Indicates that configuration changes have been made to one or more of the media devices associated with the line device. The application, if it desires, can use lineGetDevConfig to read the updated information. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version will not receive any notification.
LINEDEVSTATE_TRANSLATECHANGE
Indicates that, due to configuration changes made by the user or other circumstances, one or more of the members in the LINETRANSLATECAPS structure have changed. The application should use lineGetTranslateCaps to read the updated structure. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version will receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI to obtain the updated information.
LINEDEVSTATE_COMPLCANCEL
Indicates that the call completion identified by the completion identifier contained in the dwParam2 parameter of the LINE_LINEDEVSTATE message has been externally canceled and is no longer considered valid (if that value were to be passed in a subsequent call to lineUncompleteCall, the function would fail with LINEERR_INVALCOMPLETIONID). If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated TAPI version 1.4 or later; applications negotiating a previous API version will not receive any notification.
LINEDEVSTATE_REMOVED
Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A LINE_LINEDEVSTATE message with this value will normally be immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized will result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version will not receive any notification.

No extensibility. All 32 bits are reserved.

See Also

LINE_CLOSE, LINE_LINEDEVSTATE, LINEDEVCAPS, lineGetDevCaps, lineGetDevConfig, lineGetTranslateCaps, LINETRANSLATECAPS, lineUncompleteCall


LINEDEVSTATUSFLAGS_ Constants

The LINEDEVSTATUSFLAGS_ bit-flag constants describe a collection of Boolean line device status items.

LINEDEVSTATUSFLAGS_CONNECTED
Specifies whether the line is connected to TAPI. If TRUE, the line is connected and TAPI is able to operate on the line device. If FALSE, the line is disconnected and the application is unable to control the line device through TAPI.
LINEDEVSTATUSFLAGS_MSGWAIT
Indicates whether the line has a message waiting. If TRUE, a message is waiting; if FALSE, no message is waiting.
LINEDEVSTATUSFLAGS_INSERVICE
Indicates whether the line is in service. If TRUE, the line is in service; if FALSE, the line is out of service.
LINEDEVSTATUSFLAGS_LOCKED
Indicates whether the line is locked or unlocked. This bit is most often used with line devices associated with cellular phones. Many cellular phones have a security mechanism that requires the entry of a password to enable the phone to place calls. This bit can be used to indicate to applications that the phone is locked and cannot place calls until the password is entered on the user interface of the phone so that the application can present an appropriate alert to the user.

No extensibility. All 32 bits are reserved.

LINEDEVSTATUSFLAGS_ constants are used within the dwDevStatusFlags member of the LINEDEVSTATUS data structure.


LINEDIALTONEMODE_ Constants

The LINEDIALTONEMODE_ bit-flag constants describe different types of dial tones. A special dial tone typically carries a special meaning (as with message waiting).

LINEDIALTONEMODE_NORMAL
This is a normal dial tone, which typically is a continuous tone.
LINEDIALTONEMODE_SPECIAL
This is a special dial tone indicating that a certain condition (known by the switch or network) is currently in effect. Special dial tones typically use an interrupted tone. As with a normal dial tone, this indicates that the switch is ready to receive the number to be dialed.
LINEDIALTONEMODE_INTERNAL
This is an internal dial tone, as within a PBX.
LINEDIALTONEMODE_EXTERNAL
This is an external (public network) dial tone.
LINEDIALTONEMODE_UNKNOWN
The dial tone mode is not currently known but may become known later.
LINEDIALTONEMODE_UNAVAIL
The dial tone mode is unavailable and will not become known.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

The LINEDIALTONEMODE_ constants are used within the LINECALLSTATUS data structure for a call in the dialtone state.


LINEDIGITMODE_ Constants

The LINEDIGITMODE_ constants describe different types of inband digit generation.

LINEDIGITMODE_PULSE
Uses rotary pulse sequences to signal digits. Valid digits are 0 through 9.
LINEDIGITMODE_DTMF
Uses DTMF tones to signal digits. Valid digits are 0 through 9, '*', '#', 'A', 'B', 'C', and 'D'.
LINEDIGITMODE_DTMFEND
Uses DTMF tones to signal digits and detect the down edges. Valid digits are 0 through 9, '*', '#', 'A', 'B', 'C', and 'D'.

No extensibility. All 32 bits are reserved.

A digit mode can be specified when generating or detecting digits. Note that pulse digits are generated by making and breaking the local loop circuit. These pulses are absorbed by the switch. The remote end merely observes this as a series of inband audio clicks. Detecting digits sent as pulses must therefore be able to detect these sequences of 1 to 10 audible clicks.


LINEDISCONNECTMODE_ Constants

The LINEDISCONNECTMODE_ bit-flag constants describe different reasons for a remote disconnect request. A disconnect mode is available as call status to the application after the call state transitions to disconnected.

LINEDISCONNECTMODE_NORMAL
This is a normal disconnect request by the remote party. The call was terminated normally.
LINEDISCONNECTMODE_UNKNOWN
The reason for the disconnect request is unknown but may become known later.
LINEDISCONNECTMODE_REJECT
The remote user has rejected the call.
LINEDISCONNECTMODE_PICKUP
The call was picked up from elsewhere.
LINEDISCONNECTMODE_FORWARDED
The call was forwarded by the switch.
LINEDISCONNECTMODE_BUSY
The remote user's station is busy.
LINEDISCONNECTMODE_NOANSWER
The remote user's station does not answer.
LINEDISCONNECTMODE_BADADDRESS
The destination address is invalid.
LINEDISCONNECTMODE_UNREACHABLE
The remote user could not be reached.
LINEDISCONNECTMODE_CONGESTION
The network is congested.
LINEDISCONNECTMODE_INCOMPATIBLE
The remote user's station equipment is incompatible with the type of call requested.
LINEDISCONNECTMODE_UNAVAIL
The reason for the disconnect is unavailable and will not become known later.
LINEDISCONNECTMODE_NODIALTONE
A dial tone was not detected within a service-provider defined timeout, at a point during dialing when one was expected (such as at a "W" in the dialable string). This can also occur without a service-provider-defined timeout period or without a value specified in the dwWaitForDialTone member of the LINEDIALPARAMS structure.
LINEDISCONNECTMODE_NUMBERCHANGED
The call could not be connected because the destination number has been changed, but automatic redirection to the new number is not provided.
LINEDISCONNECTMODE_OUTOFORDER
The call could not be connected or was disconnected because the destination device is out of order (hardware failure).
LINEDISCONNECTMODE_TEMPFAILURE
The call could not be connected or was disconnected because of a temporary failure in the network; the call can be reattempted later and will eventually complete.

LINEDISCONNECTMODE_TEMPFAILURE is appropriate as a delayed response. For example, a modem getting a busy signal or equivalent too many times in a particular time period concludes that the number should not be called again until a defined time has elapsed and issues a 'delayed' response.

LINEDISCONNECTMODE_QOSUNAVAIL
The call could not be connected or was disconnected because the minimum quality of service could not be obtained or sustained. This differs from LINEDISCONNECTMODE_INCOMPATIBLE in that the lack of resources may be a temporary condition at the destination.
LINEDISCONNECTMODE_BLOCKED
The call could not be connected because calls from the origination address are not being accepted at the destination address. This differs from LINEDISCONNECTMODE_REJECT in that blocking is implemented in the network (a passive reject) while a rejection is implemented in the destination equipment (an active reject). The blocking can be due to a specific exclusion of the origination address, or because the destination accepts calls from only a selected set of origination address (closed user group).

LINEDISCONNECTMODE_BLOCKED is appropriate as a blacklisted response. For example, a modem has received an answer, gone more than six seconds without detecting Ringback, failed to connect a defined number of times, determines that the phone number is not valid to call, and issues a 'blacklisted' response.

LINEDISCONNECTMODE_DONOTDISTURB
The call could not be connected because the destination has invoked the Do Not Disturb feature.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

A remote disconnect request for a given call results in the call state transitioning to the disconnected state and a LINE_CALLSTATE message is sent to the application. The LINEDISCONNECTMODE_ information provides details about the remote disconnect request. It is available in the call's LINECALLSTATUS structure when the call is in the disconnected state. While a call is in this state, the application is still allowed to query the call's information and status. For example, user-user information that is received as part of the remote disconnect is available then. The application can clear a disconnected call by dropping the call.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use this LINEDISCONNECTMODE_ value if it is not supported on the negotiated version (LINEDISCONNECTMODE_NORMAL or _UNKNOWN could be used instead).

See Also

LINE_CALLSTATE, LINECALLSTATUS, LINEDIALPARAMS


LINEERR_ Constants

This is the list of error codes that TAPI can return when invoking operations on lines, addresses, or calls. Consult the individual function descriptions to determine which of these error codes a particular function can return.

LINEERR_ADDRESSBLOCKED
The specified address is blocked from being dialed on the specified call.
LINEERR_ALLOCATED
The line cannot be opened due to a persistent condition, such as that of a serial port being exclusively opened by another process.
LINEERR_BADDEVICEID
The specified device identifier or line device identifier (such as in a dwDeviceID parameter) is invalid or out of range.
LINEERR_BEARERMODEUNAVAIL
The call's bearer mode cannot be changed to the specified bearer mode.
LINEERR_CALLUNAVAIL
All call appearances on the specified address are currently in use.
LINEERR_COMPLETIONOVERRUN
The maximum number of outstanding call completions has been exceeded.
LINEERR_CONFERENCEFULL
The maximum number of parties for a conference has been reached, or the requested number of parties cannot be satisfied.
LINEERR_DIALBILLING
The dialable address parameter contains dialing control characters that are not processed by the service provider.
LINEERR_DIALQUIET
The dialable address parameter contains dialing control characters that are not processed by the service provider.
LINEERR_DIALDIALTONE
The dialable address parameter contains dialing control characters that are not processed by the service provider.
LINEERR_DIALPROMPT
The dialable address parameter contains dialing control characters that are not processed by the service provider.
LINEERR_INCOMPATIBLEAPIVERSION
The application requested an API version or version range that is either incompatible or cannot be supported by the Telephony API implementation and/or corresponding service provider.
LINEERR_INCOMPATIBLEEXTVERSION
The application requested an extension version range that is either invalid or cannot be supported by the corresponding service provider.
LINEERR_INIFILECORRUPT
The telephon.ini file cannot be read or understood properly by TAPI because of internal inconsistencies or formatting problems. For example, the [Locations], [Cards], or [Countries] section of the telephon.ini file may be corrupted or inconsistent.
LINEERR_INUSE
The line device is in use and cannot currently be configured, allow a party to be added, allow a call to be answered, allow a call to be placed, or allow a call to be transferred.
LINEERR_INVALADDRESS
A specified address is either invalid or not allowed. If invalid, the address contains invalid characters or digits, or the destination address contains dialing control characters (W, @, $, or ?) that are not supported by the service provider. If not allowed, the specified address is either not assigned to the specified line or is not valid for address redirection.
LINEERR_INVALADDRESSID
The specified address identifier is either invalid or out of range.
LINEERR_INVALADDRESSMODE
The specified address mode is invalid.
LINEERR_INVALADDRESSSTATE
dwAddressStates contains one or more bits that are not LINEADDRESSSTATE_ constants.
LINEERR_INVALAGENTACTIVITY
The specified agent activity is not valid.
LINEERR_INVALAGENTGROUP
The specified agent group information is not valid or contains errors. The requested action has not been carried out.
LINEERR_INVALAGENTID
The specified agent identifier is not valid.
LINEERR_INVALAGENTSKILL
The specified agent skill information is not valid.
LINEERR_INVALAGENTSTATE
The specified agent state is not valid or contains errors. No changes have been made to the agent state of the specified address.
LINEERR_INVALAGENTSUPERVISOR
The specified agent supervisor information is not valid.
LINEERR_INVALAPPHANDLE
The application handle (such as specified by a hLineApp parameter) or the appliction registration handle is invalid.
LINEERR_INVALAPPNAME
The specified application name is invalid. If an application name is specified by the application, it is assumed that the string does not contain any non-displayable characters, and is zero-terminated.
LINEERR_INVALBEARERMODE
The specified bearer mode is invalid.
LINEERR_INVALCALLCOMPLMODE
The specified completion is invalid.
LINEERR_INVALCALLHANDLE
The specified call handle is not valid. For example, the handle is not NULL but does not belong to the given line. In some cases, the specified call device handle is invalid.
LINEERR_INVALCALLPARAMS
The specified call parameters are invalid.
LINEERR_INVALCALLPRIVILEGE
The specified call privilege parameter is invalid.
LINEERR_INVALCALLSELECT
The specified select parameter is invalid.
LINEERR_INVALCALLSTATE
The current state of a call is not in a valid state for the requested operation.
LINEERR_INVALCALLSTATELIST
The specified call state list is invalid.
LINEERR_INVALCARD
The permanent card identifier specified in dwCard could not be found in any entry in the [Cards] section in the registry.
LINEERR_INVALCOMPLETIONID
The completion identifier is invalid.
LINEERR_INVALCONFCALLHANDLE
The specified call handle for the conference call is invalid or is not a handle for a conference call.
LINEERR_INVALCONSULTCALLHANDLE
The specified consultation call handle is invalid.
LINEERR_INVALCOUNTRYCODE
The specified country code is invalid.
LINEERR_INVALDEVICECLASS
The line device has no associated device for the given device class, or the specified line does not support the indicated device class.
LINEERR_INVALDIGITLIST
The specified digit list is invalid.
LINEERR_INVALDIGITMODE
The specified digit mode is invalid.
LINEERR_INVALDIGITS
The specified termination digits are not valid.
LINEERR_INVALFEATURE
The dwFeature parameter is invalid.
LINEERR_INVALGROUPID
The specified group identifier is invalid.
LINEERR_INVALLINEHANDLE
The specified call, device, line device, or line handle is invalid.
LINEERR_INVALLINESTATE
The device configuration may not be changed in the current line state. The line may be in use by another application or a dwLineStates parameter contains one or more bits that are not LINEDEVSTATE_ constants. The LINEERR_INVALLINESTATE value can also indicate that the device is DISCONNECTED or OUTOFSERVICE. These states are indicated by setting the bits corresponding to the LINEDEVSTATUSFLAGS_CONNECTED and LINEDEVSTATUSFLAGS_INSERVICE values to 0 in the dwDevStatusFlags member of the LINEDEVSTATUS structure returned by the lineGetLineDevStatus function.
LINEERR_INVALLOCATION
The permanent location identifier specified in dwLocation could not be found in any entry in the [Locations] section in the registry.
LINEERR_INVALMEDIALIST
The specified media list is invalid.
LINEERR_INVALMEDIAMODE
The list of media types to be monitored contains invalid information, the specified media mode parameter is invalid, or the service provider does not support the specified media mode. The media modes supported on the line are listed in the dwMediaModes member in the LINEDEVCAPS structure.
LINEERR_INVALMESSAGEID
The number given in dwMessageID is outside the range specified by the dwNumCompletionMessages member in the LINEADDRESSCAPS structure.
LINEERR_INVALPARAM
A parameter (such as dwTollListOption, dwTranslateOptions, dwNumDigits, or a structure pointed to by lpDeviceConfig) contains invalid values, a country code is invalid, a window handle is invalid, or the specified forward list parameter contains invalid information.
LINEERR_INVALPARKMODE
The specified park mode is invalid.
LINEERR_INVALPASSWORD
The specified password is not correct and the requested action has not been carried out.
LINEERR_INVALPOINTER
One or more of the specified pointer parameters (such as lpCallList, lpdwAPIVersion, lpExtensionID, lpdwExtVersion, lphIcon, lpLineDevCaps, and lpToneList) are invalid, or a required pointer to an output parameter is NULL.
LINEERR_INVALPRIVSELECT
An invalid flag or combination of flags was set for the dwPrivileges parameter.
LINEERR_INVALRATE
The specified bearer mode is invalid.
LINEERR_INVALREQUESTMODE
The specified request mode is invalid.
LINEERR_INVALTERMINALID
The specified terminal mode parameter is invalid.
LINEERR_INVALTERMINALMODE
The specified terminal modes parameter is invalid.
LINEERR_INVALTIMEOUT
Timeouts are not supported or the values of either or both of the parameters dwFirstDigitTimeout or dwInterDigitTimeout fall outside the valid range specified by the call's line-device capabilities.
LINEERR_INVALTONE
The specified custom tone does not represent a valid tone or is made up of too many frequencies or the specified tone structure does not describe a valid tone.
LINEERR_INVALTONELIST
The specified tone list is invalid.
LINEERR_INVALTONEMODE
The specified tone mode parameter is invalid.
LINEERR_INVALTRANSFERMODE
The specified transfer mode parameter is invalid.
LINEERR_LINEMAPPERFAILED
LINEMAPPER was the value passed in the dwDeviceID parameter, but no lines were found that match the requirements specified in the lpCallParams parameter.
LINEERR_NOCONFERENCE
The specified call is not a conference call handle or a participant call.
LINEERR_NODEVICE
The specified device identifier, which was previously valid, is no longer accepted because the associated device has been removed from the system since TAPI was last initialized. Alternately, the line device has no associated device for the given device class.
LINEERR_NODRIVER
Either tapiaddr.dll could not be located or the telephone service provider for the specified device found that one of its components is missing or corrupt in a way that was not detected at initialization time. The user should be advised to use the Telephony Control Panel to correct the problem.
LINEERR_NOMEM
Insufficient memory to perform the operation, or unable to lock memory.
LINEERR_NOMULTIPLEINSTANCE
A telephony service provider which does not support multiple instances is listed more than once in the [Providers] section in the registry. The application should advise the user to use the Telephony Control Panel to remove the duplicated driver.
LINEERR_NOREQUEST
There currently is no request pending of the indicated mode, or the application is no longer the highest-priority application for the specified request mode.
LINEERR_NOTOWNER
The application does not have owner privilege to the specified call.
LINEERR_NOTREGISTERED
The application is not registered as a request recipient for the indicated request mode.
LINEERR_OPERATIONFAILED
The operation failed for an unspecified or unknown reason.
LINEERR_OPERATIONUNAVAIL
The operation is not available, such as for the given device or specified line.
LINEERR_RATEUNAVAIL
The service provider currently does not have enough bandwidth available for the specified rate.
LINEERR_REINIT
If TAPI reinitialization has been requested, for example as a result of adding or removing a telephony service provider, then lineInitialize, lineInitializeEx, or lineOpen requests are rejected with this error until the last application shuts down its usage of the API (using lineShutdown), at which time the new configuration becomes effective and applications are once again permitted to call lineInitialize or lineInitializeEx.
LINEERR_RESOURCEUNAVAIL
Insufficient resources to complete the operation. For example, a line cannot be opened due to a dynamic resource overcommitment.
LINEERR_STRUCTURETOOSMALL
The dwTotalSize member indicates insufficient space to contain the fixed portion of the specified structure.
LINEERR_TARGETNOTFOUND
A target for the call handoff was not found. This can occur if the named application did not open the same line with the LINECALLPRIVILEGE_OWNER bit in the dwPrivileges parameter of lineOpen. Or, in the case of media-mode handoff, no application has opened the same line with the LINECALLPRIVILEGE_OWNER bit in the dwPrivileges parameter of lineOpen and with the media mode specified in the dwMediaMode parameter having been specified in the dwMediaModes parameter of lineOpen.
LINEERR_TARGETSELF
The application invoking this operation is the target of the indirect handoff. That is, TAPI has determined that the calling application is also the highest priority application for the given media mode.
LINEERR_UNINITIALIZED
The operation was invoked before any application called lineInitialize , lineInitializeEx.
LINEERR_USERUSERINFOTOOBIG
The string containing user-user information exceeds the maximum number of bytes specified in the dwUUIAcceptSize, dwUUIAnswerSize, dwUUIDropSize, dwUUIMakeCallSize, or dwUUISendUserUserInfoSize member of LINEDEVCAPS, or the string containing user-user information is too long.

The values 0xC0000000 through 0xFFFFFFFF are available for device-specific extensions. The values 0x80000000 through 0xBFFFFFFF are reserved, while 0x00000000 through 0x7FFFFFFF are used as request identifiers.

If an application gets an error return that it does not specifically handle (such as an error defined by a device-specific extension), it should treat the error as a LINEERR_OPERATIONFAILED (for an unspecified reason).

See Also

LINEADDRESSCAPS, LINEDEVCAPS, LINEDEVSTATUS, lineGetLineDevStatus, lineInitialize, lineInitializeEx, lineOpen, lineShutdown


LINEFEATURE_ Constants

The LINEFEATURE_ constants list the operations that can be invoked on a line using this API.

LINEFEATURE_DEVSPECIFIC
Device-specific operations can be used on the line.
LINEFEATURE_DEVSPECIFICFEAT
Device-specific features can be used on the line.
LINEFEATURE_FORWARD
Forwarding of all addresses can be used on the line.
LINEFEATURE_MAKECALL
An outgoing call can be placed on this line using an unspecified address.
LINEFEATURE_SETMEDIACONTROL
Media control can be set on this line.
LINEFEATURE_SETTERMINAL
Terminal modes for this line can be set.
LINEFEATURE_SETDEVSTATUS
The lineSetLineDevStatus function can be invoked on the line device.
LINEFEATURE_FORWARDFWD
The lineForward function can be used to forward calls on all address on the line to other numbers. LINEFEATURE_FORWARD will also be set.
LINEFEATURE_FORWARDDND
The lineForward function (with an empty destination address) can be used to turn on the Do Not Disturb feature on all addresses on the line. LINEFEATURE_FORWARD will also be set.

Note If neither of the new modified "FORWARD" bits is set in the dwLineFeatures member in LINEDEVSTATUS but the LINEFEATURE_FORWARD bit is set, then any of the forward modes can work; the service provider has simply not specified which ones.

No extensibility. All 32 bits are reserved.

The LINEFEATURE_ constants are used in LINEDEVSTATUS (returned by lineGetLineDevStatus). LINEDEVSTATUS reports, for a given line, which line features can actually be invoked while the line is in the current state. An application would make this determination dynamically after line state changes, typically caused by address or call-related activities on the line.

See Also

LINEDEVSTATUS, lineForward, lineGetLineDevStatus, lineSetLineDevStatus


LINEFORWARDMODE_ Constants

The LINEFORWARDMODE_ bit-flag constants describe the conditions under which calls to an address can be forwarded.

LINEFORWARDMODE_UNCOND
Forward all calls unconditionally, irrespective of their origin. Use this value when unconditional forwarding for internal and external calls cannot be controlled separately. Unconditional forwarding overrides forwarding on busy and/or no answer conditions.
LINEFORWARDMODE_UNCONDINTERNAL
Forward all internal calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.
LINEFORWARDMODE_UNCONDEXTERNAL
Forward all external calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.
LINEFORWARDMODE_UNCONDSPECIFIC
Unconditionally forward all calls that originated at a specified address (selective call forwarding).
LINEFORWARDMODE_BUSY
Forward all calls on busy, irrespective of their origin. Use this value when forwarding for internal and external calls on busy and on no answer cannot be controlled separately.
LINEFORWARDMODE_BUSYINTERNAL
Forward all internal calls on busy. Use this value when forwarding for internal and external calls on busy and on no answer can be controlled separately.
LINEFORWARDMODE_BUSYEXTERNAL
Forward all external calls on busy. Use this value when forwarding for internal and external calls on busy and on no answer can be controlled separately.
LINEFORWARDMODE_BUSYSPECIFIC
Forward on busy all calls that originated at a specified address (selective call forwarding).
LINEFORWARDMODE_NOANSW
Forward all calls on no answer, irrespective of their origin. Use this value when call forwarding for internal and external calls on no answer cannot be controlled separately.
LINEFORWARDMODE_NOANSWINTERNAL
Forward all internal calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.
LINEFORWARDMODE_NOANSWEXTERNAL
Forward all external calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.
LINEFORWARDMODE_NOANSWSPECIFIC
Forward on no answer all calls that originated at a specified address (selective call forwarding).
LINEFORWARDMODE_BUSYNA
Forward all calls on busy/no answer, irrespective of their origin. Use this value when forwarding for internal and external calls on busy and on no answer cannot be controlled separately.
LINEFORWARDMODE_BUSYNAINTERNAL
Forward all internal calls on busy/no answer. Use this value when call forwarding on busy and on no answer cannot be controlled separately for internal calls.
LINEFORWARDMODE_BUSYNAEXTERNAL
Forward all external calls on busy/no answer. Use this value when call forwarding on busy and on no answer cannot be controlled separately for internal calls.
LINEFORWARDMODE_BUSYNASPECIFIC
Forward on busy/no answer all calls that originated at a specified address (selective call forwarding).
LINEFORWARDMODE_UNKNOWN
Calls are forwarded, but the conditions under which forwarding will occur are not known at this time. It is possible that the conditions may become known at a future time.
LINEFORWARDMODE_UNAVAIL
Calls are forwarded, but the conditions under which forwarding will occur are not known, and will never be known by the service provider.

No extensibility. All 32 bits are reserved.

The bit flags defined by LINEFORWARDMODE_ are not orthogonal. Unconditional forwarding ignores any specific condition such as busy or no answer. If unconditional forwarding is not in effect, then forwarding on busy and on no answer can be controlled separately or not separately. If controlled separately, the LINEFORWARDMODE_BUSY and LINEFORWARDMODE_NOANSW flags can be used separately. If not controlled separately, the flag LINEFORWARDMODE_BUSYNA must be used. Similarly, if forwarding of internal and external calls can be controlled separately, then LINEFORWARDMODE_INTERNAL and LINEFORWARDMODE_EXTERNAL flags can be used separately; otherwise the combination is used.

Address capabilities indicate which forwarding modes are available for each address assigned to a line. An application can use lineForward to set forwarding conditions at the switch.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use these LINEFORWARDMODE_ values if i not supported on the negotiated version.


LINEGATHERTERM_ Constants

The LINEGATHERTERM_ bit-flag constants describe the conditions under which buffered digit gathering is terminated.

LINEGATHERTERM_BUFFERFULL
The requested number of digits has been gathered. The buffer is full.
LINEGATHERTERM_TERMDIGIT
One of the termination digits matched a received digit. The matched termination digit is the last digit in the buffer.
LINEGATHERTERM_FIRSTTIMEOUT
The first digit timeout expired. The buffer contains no digits.
LINEGATHERTERM_INTERTIMEOUT
The inter-digit timeout expired. The buffer contains at least one digit.
LINEGATHERTERM_CANCEL
The request was canceled by this application, by another application, or because the call terminated.

No extensibility. All 32 bits are reserved.


LINEGENERATETERM_ Constants

The LINEGENERATETERM_ bit-flag constants describe the conditions under which digit or tone generation is terminated.

LINEGENERATETERM_DONE
The requested number of digits or requested tones have been generated for the requested duration.
LINEGENERATETERM_CANCEL
The digit or tone generation request was canceled by this application, by another application, or because the call terminated. This value can also be returned when digit or tone generation cannot be completed due to internal failure of the service provider.

No extensibility. All 32 bits are reserved.


LINELOCATIONOPTION_ Constants

The LINELOCATIONOPTION_ constants define values used in the dwOptions member of the LINELOCATIONENTRY structure returned as part of the LINETRANSLATECAPS structure returned by lineGetTranslateCaps.

LINELOCATIONOPTION_PULSEDIAL
The default dialing mode at this location is pulse dialing. If this bit is set, lineTranslateAddress will insert a "P" dial modifier at the beginning of the dialable string returned when this location is selected. If this bit is not set, lineTranslateAddress will insert a "T" dial modifier at the beginning of the dialable string.

Not extensible. All 32 bits are reserved.


LINEINITIALIZEEXOPTION_ Constants

The LINEINITIALIZEEXOPTION_ constants specify which event notification mechanism to use when initializing a session.

LINEINITIALIZEEXOPTION_USECOMPLETIONPORT
The application desires to use the Completion Port event notification mechanism.
LINEINITIALIZEEXOPTION_USEEVENT
The application desires to use the Event Handle event notification mechanism.
LINEINITIALIZEEXOPTION_USEHIDDENWINDOW
The application desires to use the Hidden Window event notification mechanism.

See lineInitializeEx for further details on the operation of these options.


LINEMEDIACONTROL_ Constants

The LINEMEDIACONTROL_ bit-flag constants describe a set of generic operations on media streams. The interpretations are determined by the media stream. The line device must have the media-control capability for any media-control operation to be effective.

LINEMEDIACONTROL_NONE
No change is to be made to the media stream.
LINEMEDIACONTROL_START
Start the media stream.
LINEMEDIACONTROL_RESET
Reset the media stream. Equivalent to an end-of-input. All buffers are released.
LINEMEDIACONTROL_PAUSE
Temporarily pause the media stream.
LINEMEDIACONTROL_RESUME
Resume a paused media stream.
LINEMEDIACONTROL_RATEUP
The speed of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_RATEDOWN
The speed of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_RATENORMAL
The speed of the media stream is returned to normal.
LINEMEDIACONTROL_VOLUMEUP
The amplitude of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMEDOWN
The amplitude of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMENORMAL
The amplitude of the media stream is returned to normal.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Media control is provided to improve performance of actions on media streams in response to telephony-related events. The application should normally manage a media stream through the media-specific API. The media-control functionality provided here is not intended to replace the native media APIs.

Media-control actions can be associated with the detection of digits, the detection of tones, the transition into a call state, and the detection of a media mode. Consult a line's device capabilities to determine whether media control is available on the line.


LINEMEDIAMODE_ Constants

The LINEMEDIAMODE_ constants describe media modes (the datatype of a media stream) on calls.

LINEMEDIAMODE_UNKNOWN
A media stream exists but its mode is not currently known and may become known later. This would correspond to a call with an unclassified media type. In typical analog telephony environments, an incoming call's media mode may be unknown until after the call has been answered and the media stream has been filtered to make a determination.

If the unknown media-mode flag is set, other media flags can also be set. This is used to signify that the media is unknown but that it is likely to be one of the other selected media modes.

LINEMEDIAMODE_INTERACTIVEVOICE
The presence of voice energy on the call, and the call is treated as an interactive call with humans on both ends.
LINEMEDIAMODE_AUTOMATEDVOICE
The presence of voice energy on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM
A data modem session on the call.
LINEMEDIAMODE_G3FAX
A group 3 fax is being sent or received over the call.
LINEMEDIAMODE_TDD
A TDD (Telephony Devices for the Deaf) session on the call.
LINEMEDIAMODE_G4FAX
A group 4 fax is being sent or received over the call.
LINEMEDIAMODE_DIGITALDATA
Digital data is being sent or received over the call.
LINEMEDIAMODE_TELETEX
A teletex session on the call. Teletex is one of the telematic services.
LINEMEDIAMODE_VIDEOTEX
A videotex session on the call. Videotex is one the telematic services.
LINEMEDIAMODE_TELEX
A telex session on the call. Telex is one of the telematic services.
LINEMEDIAMODE_MIXED
A mixed session on the call. Mixed is one of the ISDN telematic services.
LINEMEDIAMODE_ADSI
An ADSI (Analog Display Services Interface) session on the call.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.

All 32 bits are reserved.

Note that bearer mode and media mode are different notions. The bearer mode of a call is an indication of the quality of the telephone connection as provided primarily by the network. The media mode of a call is an indication of the type of information stream that is exchanged over that call. Group 3 fax or data modem are media modes that use a call with a 3.1 kHz voice bearer mode.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use this LINEMEDIAMODE_ value if not supported on the negotiated version.


LINEOFFERINGMODE_ Constants

The LINEOFFERINGMODE_ bit-flag constants describe different substates of an offering call. A mode is available as call status to the application after the call state transitions to offering, and within the LINE_CALLSTATE message indicating the call is in LINECALLSTATE_OFFERING. These values are used when the call is on an address that is shared (bridged) with other stations (see LINEADDRESSSHARING_ Constants), primarily electronic key systems.

LINEOFFERINGMODE_ACTIVE
Indicates that the call is alerting at the current station (will be accompanied by LINEDEVSTATE_RINGING messages), and if any application is set up to automatically answer, it can do so. If the call state mode is ZERO, the application should assume that the value is active (which would be the situation on a non-bridged address).
LINEOFFERINGMODE_INACTIVE
Indicates that the call is being offered at more than one station, but the current station is not alerting (for example, it may be an attendant station where the offering status is advisory, such as blinking a light); software at the station set for automatic answering should preferably not answer the call, because this should be the prerogative at the primary (alerting) station, but lineAnswer may be used to connect the call.

Not extensible. All 32 bits are reserved.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the line, and to not use these LINEOFFERINGMODE_ values if not supported on the negotiated version. It should be noted that applications which are not cognizant of LINEOFFERINGMODE_ will most likely assume that a call that is in LINECALLSTATE_OFFERING is in LINEOFFERINGMODE_ACTIVE.

The LINEOFFERINGMODE_ACTIVE and LINEOFFERINGMODE_INACTIVE values are used when the call is on an address that is shared with other stations (bridged; see LINEADDRESSSHARING_ Constants), primarily electronic key systems. If the offering call state mode is "active," it means that the call is alerting at the current station (will be accompanied by LINEDEVSTATE_RINGING messages), and if any application is set up to automatically answer, it can do so. If the call state mode is "inactive," the call is being offered at more than one station, but the current station is not alerting (for example, it may be an attendant station where the offering status is advisory, such as blinking a light); software at the station set for automatic answering should preferably not answer the call, because this should be the prerogative at the primary (alerting) station, but lineAnswer can be used to connect the call. If the call state mode is ZERO, the application should assume that the value is active (which would be the situation on a non-bridged address).


LINEOPENOPTION_ Constants

The LINEOPENOPTION_ constants list the available options for opening a line.

LINEOPENOPTION_SINGLEADDRESS
The application should be informed of new calls created on the line device only if those calls appear on the address specified in the dwAddressID member in the LINECALLPARAMS structure pointed to by the lpCallParams parameter.
LINEOPENOPTION_PROXY
The application is willing to handle requests from other applications that have the line open.

See lineOpen for further details on the operation of these options.


LINEPARKMODE_ Constants

The LINEPARKMODE_ bit-flag constants describe different ways of parking calls.

LINEPARKMODE_DIRECTED
Specifies directed call park. The address where the call is to be parked must be supplied to the switch.
LINEPARKMODE_NONDIRECTED
Specifies nondirected call park. The address where the call is parked is selected by the switch and provided by the switch to the application.

No extensibility. All 32 bits are reserved.

The LINEPARKMODE_ constants are used when parking a call. Consult a line's address device capabilities to find out which park mode is available.


LINEPROXYREQUEST_ Constants

These constants are used in two contexts. First, they can be used in an array of DWORD values in the LINECALLPARAMS structure passed in with lineOpen when the LINEOPENOPTION_PROXY option is specified, to indicate which functions the application is willing to handle. Second, they are used in the LINEPROXYBUFFER passed to the handler application by a LINE_PROXYREQUEST message to indicate the type of request that is to be processed and the format of the data in the buffer.

LINEPROXYREQUEST_SETAGENTGROUP
Associated with lineSetAgentGroup.
LINEPROXYREQUEST_SETAGENTSTATE
Associated with lineSetAgentState.
LINEPROXYREQUEST_SETAGENTACTIVITY
Associated with lineSetAgentActivity.
LINEPROXYREQUEST_GETAGENTCAPS
Associated with lineGetAgentCaps.
LINEPROXYREQUEST_GETAGENTSTATUS
Associated with lineGetAgentStatus.
LINEPROXYREQUEST_AGENTSPECIFIC
Associated with lineAgentSpecific.
LINEPROXYREQUEST_GETAGENTACTIVITYLIST
Associated with lineGetAgentActivityList.
LINEPROXYREQUEST_GETAGENTGROUPLIST
Associated with lineGetAgentGroupList.


LINEREMOVEFROMCONF_ Constants

The LINEREMOVEFROMCONF_ scalar constants describe how parties participating in a conference call can be removed from a conference call.

LINEREMOVEFROMCONF_NONE
Parties cannot be removed from the conference call.
LINEREMOVEFROMCONF_LAST
Only the most recently added party can be removed from the conference call
LINEREMOVEFROMCONF_ANY
Any participating party can be removed from the conference call.

No extensibility. All 32 bits are reserved.


LINEREQUESTMODE_ Constants

The LINEREQUESTMODE_ bit-flag constants describe different types of telephony requests that can be made from one application to another.

LINEREQUESTMODE_MAKECALL
A tapiRequestMakeCall request.

No extensibility. All 32 bits are reserved.


LINEROAMMODE_ Constants

The LINEROAMMODE_ bit-flag constants describe the roaming status of a line device.

LINEROAMMODE_UNKNOWN
The roam mode is currently unknown but may become known later.
LINEROAMMODE_UNAVAIL
The roam mode is unavailable and will not be known.
LINEROAMMODE_HOME
The line is connected to the home network node.
LINEROAMMODE_ROAMA
The line is connected to the Roam-A carrier and calls are charged accordingly.
LINEROAMMODE_ROAMB
The line is connected to the Roam-B carrier and calls are charged accordingly.

No extensibility. All 32 bits are reserved.


LINESPECIALINFO_ Constants

The LINESPECIALINFO_ bit-flag constants describes special information signals that the network can use to report various reporting and network observation operations. They are special coded tone sequences transmitted at the beginning of network advisory recorded announcements.

LINESPECIALINFO_NOCIRCUIT
This special information tone precedes a no circuit or an emergency announcement (trunk blockage category).
LINESPECIALINFO_CUSTIRREG
This special information tone precedes a vacant number, AIS, Centrex number change and nonworking station, access code not dialed or dialed in error, or manual intercept operator message (customer irregularity category). LINESPECIALINFO_CUSTIRREG is also reported when billing information is rejected and when the dialed address is blocked at the switch.
LINESPECIALINFO_REORDER
This special information tone precedes a reorder announcement (equipment irregularity category). LINESPECIALINFO_REORDER is also reported when the telephone is kept offhook too long.
LINESPECIALINFO_UNKNOWN
Specifics about the special information tone are currently unknown but may become known later.
LINESPECIALINFO_UNAVAIL
Specifics about the special information tone are unavailable and will not become known.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Special information tones are defined for advisory messages and are not normally used for billing or supervisory purpose.


LINETERMDEV_ Constants

The LINETERMDEV_ bit-flag constants describe different types of terminal devices.

LINETERMDEV_PHONE
The terminal is a phone set.
LINETERMDEV_HEADSET
The terminal is a headset.
LINETERMDEV_SPEAKER
The terminal is an external speaker and microphone.

No extensibility. All 32 bits are reserved.

These constants are used to characterize a line's terminal device and help an application to determine the nature of a terminal device.


LINETERMMODE_ Constants

The LINETERMMODE_ bit-flag constants describe different types of events on a phone line that can be routed to a terminal device.

LINETERMMODE_BUTTONS
These are button-press events sent from the terminal to the line.
LINETERMMODE_LAMPS
These are lamp events sent from the line to the terminal.
LINETERMMODE_DISPLAY
This is display information sent from the line to the terminal.
LINETERMMODE_RINGER
This is ringer-control information sent from the switch to the terminal.
LINETERMMODE_HOOKSWITCH
These are hookswitch events sent from the terminal to the line.
LINETERMMODE_MEDIATOLINE
This is the unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIAFROMLINE
This is the unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when the routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIABIDIRECT
This is the bidirectional media stream associated with a call on the line and the terminal. Use this value when the routing of both unidirectional channels of a call's media stream cannot be controlled independently.

No extensibility. All 32 bits are reserved.

These constants describe the classes of control and information streams that can be routed directly between a line device and a terminal device (such as a phone set).


LINETERMSHARING_ Constants

The LINETERMSHARING_ bit-flag constants describe different ways in which a terminal can be shared between line devices, addresses, or calls.

LINETERMSHARING_PRIVATE
The terminal device is private to a single line device.
LINETERMSHARING_SHAREDEXCL
The terminal device can be used by multiple lines. The last line device to do a lineSetTerminal to the terminal for a given terminal mode will have exclusive connection to the terminal for that mode.
LINETERMSHARING_SHAREDCONF
The terminal device can be used by multiple lines. The lineSetTerminal requests of the various terminals end up being merged or conferenced at the terminal.

No extensibility. All 32 bits are reserved.

These constants describe the classes of control and information streams that can be routed directly between a line device and a terminal device (such as a phone set).


LINETOLLLISTOPTION_ Constants

The LINETOLLLISTOPTION_ bit-flag constants describe options for manipulating a toll list.

LINETOLLLISTOPTION_ADD
A prefix is to be added to the toll list.
LINETOLLLISTOPTION_REMOVE
A prefix is to be removed from the toll list.

No extensibility. All 32 bits are reserved.


LINETONEMODE_ Constants

The LINETONEMODE_ constants describe different selections that are used when generating line tones.

LINETONEMODE_CUSTOM
The tone is a custom tone defined by its component frequencies, of type LINEGENERATETONE.
LINETONEMODE_RINGBACK
The tone is ringback tone. Exact definition is service-provider defined.
LINETONEMODE_BUSY
The tone is a busy tone. Exact definition is service-provider defined.
LINETONEMODE_BEEP
The tone is a beep, such as that used to announce the beginning of a recording. Exact definition is service-provider defined.
LINETONEMODE_BILLING
The tone is a billing information tone such as a credit card prompt tone. Exact definition is service-provider defined.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

These constants are used to define tones to be generated inband over a call to the remote party. Note that tone detection of non-custom tones does not use these constants.


LINETRANSFERMODE_ Constants

The LINETRANSFERMODE_ bit-flag constants describe different ways of resolving call transfer requests.

LINETRANSFERMODE_TRANSFER
The transfer is resolved by transferring the initial call to the consultation call. Both calls will become idle to the application.
LINETRANSFERMODE_CONFERENCE
The transfer is resolved by establishing a three-way conference between the application, the party connected to the initial call, and the party connected to the consultation call. A conference call is created when this option is selected.

No extensibility. All 32 bits are reserved.


LINETRANSLATEOPTION_ Constants

The LINETRANSLATEOPTION_ bit-flag constant describes an option used by address translation.

LINETRANSLATEOPTION_CARDOVERRIDE
The default calling card is to be overidden with a specified one.
LINETRANSLATEOPTION_CANCELCALLWAITING
If a Cancel Call Waiting string is defined for the location, setting this bit will cause that string to be inserted at the beginning of the dialable string. This is commonly used by data modem and fax applications to prevent interruption of calls by call waiting beeps. If no Cancel Call Waiting string is defined for the location, this bit has no affect. Note that applications using this bit are advised to also set the LINECALLPARAMFLAGS_SECURE bit in the dwCallParamFlags member of the LINECALLPARAMS structure passed in to lineMakeCall through the lpCallParams parameter, so that if the line device uses a mechanism other than dialable digits to suppress call interrupts that that mechanism will be invoked.
LINETRANSLATEOPTION_FORCELOCAL
If the number is local but would have been translated as a long distance call (LINETRANSLATERESULT_INTOLLLIST bit set in the LINETRANSLATEOUTPUT structure), this option will force it to be translated as local. This is a temporary override of the toll list setting.
LINETRANSLATEOPTION_FORCELD
If the address could potentially have been a toll call, but would have been translated as a local call (LINETRANSLATERESULT_NOTINTOLLLIST bit set in the LINETRANSLATEOUTPUT structure), this option will force it to be translated as long distance. This is a temporary override of the toll list setting.

No extensibility. All 32 bits are reserved.

See Also

LINECALLPARAMS, lineMakeCall, LINETRANSLATEOUTPUT


LINETRANSLATERESULT_ Constants

The LINETRANSLATERESULT_ bit-flag constants describe various results of an address translation.

LINETRANSLATERESULT_CANONICAL
Indicates that the input string was in valid canonical format.
LINETRANSLATERESULT_INTERNATIONAL
Indicates that the call is being treated as an international call (country code specified in the destination address is different from the country code specified for the CurrentLocation).
LINETRANSLATERESULT_LONGDISTANCE
Indicates that the call is being treated as a long distance call (country code specified in the destination address is the same but area code is different from those specified for the CurrentLocation).
LINETRANSLATERESULT_LOCAL
Indicates that the call is being treated as a local call (country code and area code specified in the destination address are the same as those specified for the CurrentLocation).
LINETRANSLATERESULT_INTOLLLIST
Indicates that the local call is being dialed as long distance because the country has toll calling and the prefix appears in the TollPrefixList of the CurrentLocation.
LINETRANSLATERESULT_NOTINTOLLLIST
Indicates that the country supports toll calling but the prefix does not appear in the TollPrefixList, so the call is dialed as a local call. Note that if both INTOLLIST and NOTINTOLLIST are off, the current country does not support toll prefixes, and user-interface elements related to toll prefixes should not be presented to the user; if either such bit is on, the country does support toll lists, and the related user-interface elements should be enabled.
LINETRANSLATERESULT_DIALBILLING
Indicates that the returned address contains a "$".
LINETRANSLATERESULT_DIALQUIET
Indicates that the returned address contain a "@".
LINETRANSLATERESULT_DIALDIALTONE
Indicates that the returned address contains a "W".
LINETRANSLATERESULT_DIALPROMPT
Indicates that the returned address contains a "?".
LINETRANSLATERESULT_VOICEDETECT
Indicates that the returned dialable address contains a ":".

Note The ":" (colon) character will be added to the list of characters which can be embedded in a dialable string and passed into destination addresses. Attempting to pass it from an application to a line device that supports an API version earlier than 2.0 will most likely result in LINEERR_INVALADDRESS, or possibly in the character being ignored entirely. The meaning of this character is "Pause until a voice prompt is detected, then continue dialing"; it is intended for use when automatically dialing into systems that give voice prompts, such as long distance calling card processors.

No extensibility. All 32 bits are reserved.


LINETSPIOPTION_ Constants

LINETSPIOPTION_NONREENTRANT
TAPI should call functions in this service provider one at a time; it should wait from each function to return (but not for asynchronous functions to complete) before calling the same or another function, either on the same or a different thread, on the same or a different processor.


Phone Device Constants

This section contains an alphabetic listing of the phone device constants used by TAPI.


PHONEBUTTONFUNCTION_ Constants

The PHONEBUTTONFUNCTION_ scalar constants describe the functions commonly assigned to buttons on telephone sets.

PHONEBUTTONFUNCTION_UNKNOWN
A "dummy" function assignment that indicates that the exact function of the button is unknown or has not been assigned.
PHONEBUTTONFUNCTION_CONFERENCE
Initiates a conference call or adds a call to a conference call.
PHONEBUTTONFUNCTION_TRANSFER
Initiates a call transfer or completes the transfer of a call.
PHONEBUTTONFUNCTION_DROP
Drops the active call.
PHONEBUTTONFUNCTION_HOLD
Places the active call on hold.
PHONEBUTTONFUNCTION_RECALL
Unholds a call.
PHONEBUTTONFUNCTION_DISCONNECT
Disconnects a call, such as after initiating a transfer.
PHONEBUTTONFUNCTION_CONNECT
Reconnects a call that is on consultation hold.
PHONEBUTTONFUNCTION_MSGWAITON
Turns on a message waiting lamp.
PHONEBUTTONFUNCTION_MSGWAITOFF
Turns off a message waiting lamp.
PHONEBUTTONFUNCTION_SELECTRING
Allows the user to select the ring pattern of the phone.
PHONEBUTTONFUNCTION_ABBREVDIAL
The number to be dialed will be indicated using a short, abbreviated number consisting of one digit or a few digits.
PHONEBUTTONFUNCTION_FORWARD
Initiates or changes call forwarding to this phone.
PHONEBUTTONFUNCTION_PICKUP
Picks up a call ringing on another phone.
PHONEBUTTONFUNCTION_RINGAGAIN
Initiates a request to be notified if a call cannot be completed normally because of a busy signal or no answer.
PHONEBUTTONFUNCTION_PARK
Parks the active call on another phone, placing it on hold there.
PHONEBUTTONFUNCTION_REJECT
Rejects an incoming call before the call has been answered.
PHONEBUTTONFUNCTION_REDIRECT
Redirects an incoming call to another extension before the call has been answered.
PHONEBUTTONFUNCTION_MUTE
Mutes the phone's microphone device.
PHONEBUTTONFUNCTION_VOLUMEUP
Increases the volume of audio through the phone's handset speaker or speakerphone.
PHONEBUTTONFUNCTION_VOLUMEDOWN
Decreases the volume of audio through the phone's handset speaker or speakerphone.
PHONEBUTTONFUNCTION_SPEAKERON
Turns the phone's external speaker on.
PHONEBUTTONFUNCTION_SPEAKEROFF
Turns the phone's external speaker off.
PHONEBUTTONFUNCTION_FLASH
Generates the equivalent of an onhook/offhook sequence. A flash typically indicates that any digits typed next are to be understood as commands to the switch. On many switches, places an active call on consultation hold.
PHONEBUTTONFUNCTION_DATAON
Indicates that the next call is a data call.
PHONEBUTTONFUNCTION_DATAOFF
Indicates that the next call is not a data call.
PHONEBUTTONFUNCTION_DONOTDISTURB
Places the phone in "do not disturb" mode; incoming calls receive a busy signal or are forwarded to an operator or voice mail system.
PHONEBUTTONFUNCTION_INTERCOM
Connects to the intercom to broadcast a page.
PHONEBUTTONFUNCTION_BRIDGEDAPP
Selects a particular appearance of a bridged address.
PHONEBUTTONFUNCTION_BUSY
Makes the phone appear "busy" to incoming calls.
PHONEBUTTONFUNCTION_CALLAPP
Selects a particular call appearance.
PHONEBUTTONFUNCTION_DATETIME
Causes the phone to display current date and time; this information would be sent by the switch.
PHONEBUTTONFUNCTION_DIRECTORY
Calls up directory service from the switch.
PHONEBUTTONFUNCTION_COVER
Forwards all calls destined for this phone to another phone used for coverage.
PHONEBUTTONFUNCTION_CALLID
Requests display of caller ID on the phone's display.
PHONEBUTTONFUNCTION_LASTNUM
Redials last number dialed.
PHONEBUTTONFUNCTION_NIGHTSRV
Places the phone in the mode it is configured for during night hours.
PHONEBUTTONFUNCTION_SENDCALLS
Sends all calls to another phone used for coverage; same as PHONEBUTTONFUNCTION_COVER.
PHONEBUTTONFUNCTION_MSGINDICATOR
Controls the message indicator lamp.
PHONEBUTTONFUNCTION_REPDIAL
Repertory dialing—the number to be dialed is provided as a shorthand following pressing of this button.
PHONEBUTTONFUNCTION_SETREPDIAL
Programs the shorthand-to-phone number mappings accessible by means of repertory dialing (the "REPDIAL" button).
PHONEBUTTONFUNCTION_SYSTEMSPEED
The number to be dialed is provided as a shorthand following pressing of this button. The mappings for system speed dialing are configured inside the switch.
PHONEBUTTONFUNCTION_STATIONSPEED
The number to be dialed is provided as a shorthand following pressing of this button. The mappings for station speed dialing are specific to this station (phone).
PHONEBUTTONFUNCTION_CAMPON
Camps-on an extension that returns a busy indication. When the remote station returns to idle, the phone will be rung with a distinctive patterns. Picking up the local phone reinitiates the call.
PHONEBUTTONFUNCTION_SAVEREPEAT
When pressed while a call or call attempt is active, it will remember that call's number or command. When pressed while no call is active (such as during dial tone), it repeats the most saved command.
PHONEBUTTONFUNCTION_QUEUECALL
Queues a call to an outside number after it encounters a trunk-busy indication. When a trunk becomes later available, the phone will be rung with a distinctive pattern. Picking up the local phone reinitiates the call.
PHONEBUTTONFUNCTION_NONE
A "dummy" function assignment that indicates that the button does not have a function.

Values in the range 0x80000000 to 0xFFFFFFFF can be assigned for device-specific extensions; values in the range 0x00000000 to 0x7FFFFFFF are reserved.

The PHONEBUTTONFUNCTION_ constants have values commonly found on current telephone sets. These button functions can be used to invoke the corresponding function from the switch using lineDevSpecificFeature. Note that TAPI does not define the semantics of the button functions; it only provides access to the corresponding function. The behavior associated with each of the function values above is generic and can vary based on the telephony environment.


PHONEBUTTONMODE_ Constants

The PHONEBUTTONMODE_ bit-flag constants describe the button classes.

PHONEBUTTONMODE_DUMMY
This value is used to describe a button/lamp position that has no corresponding button but has only a lamp.
PHONEBUTTONMODE_CALL
The button is assigned to a call appearance.
PHONEBUTTONMODE_FEATURE
The button is assigned to requesting features from the switch, such as hold, conference, and transfer.
PHONEBUTTONMODE_KEYPAD
The button is one of the twelve keypad buttons, 0 through 9, '*', and '#'.
PHONEBUTTONMODE_LOCAL
The button is a local function button, such as mute or volume control.
PHONEBUTTONMODE_DISPLAY
The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.

No extensibility. All 32 bits are reserved.

This enumeration type is used in the PHONECAPS data structure to describe the meaning associated with the phone's buttons.


PHONEBUTTONSTATE_ Constants

The PHONEBUTTONSTATE_ bit-flag constants describe the button's positions.

PHONEBUTTONSTATE_UP
The button is in the "up" state.
PHONEBUTTONSTATE_DOWN
The button is in the "down" state (pressed down).
PHONEBUTTONSTATE_UNKNOWN
Indicates that the up or down state of the button is not known at this time, but may become known at a future time.
PHONEBUTTONSTATE_UNAVAIL
Indicates that the up or down state of the button is not known to the service provider, and will not become known at a future time.

No extensibility. All 32 bits are reserved.

For backward compatibility, it is the responsibility of the service provider to examine the negotiated API version on the phone, and to not use these PHONEBUTTONSTATE_ values if not supported on the negotiated version.


PHONEERR_ Constants

This is the list of error codes that the implementation can return when invoking operations on phone devices. Consult the individual function descriptions to determine which of these error codes each function can return.

PHONEERR_ALLOCATED
The specified resource is already allocated.
PHONEERR_BADDEVICEID
The specified device identifier is invalid or out of range.
PHONEERR_INCOMPATIBLEAPIVERSION
The application requested an API version or version range that cannot be supported by the Telephony API implementation and/or corresponding service provider.
PHONEERR_INCOMPATIBLEEXTVERSION
The application requested an extension version or version range that cannot supported by the service provider.
PHONEERR_INIFILECORRUPT
Because of internal inconsistencies or formatting problems in the telephon.INI file, it cannot be read and understood properly by TAPI.
PHONEERR_INUSE
The device is currently in use. The device cannot be configured.
PHONEERR_INVALAPPHANDLE
The application's specified usage handle or registration handle is invalid.
PHONEERR_INVALAPPNAME
The specified application name is invalid. If an application name is specified by the application, it is assumed that the string does not contain any nondisplayable characters and is NULL-terminated.
PHONEERR_INVALBUTTONLAMPID
The specified button/lamp identifier is out of range or invalid.
PHONEERR_INVALBUTTONMODE
The button mode parameter is invalid.
PHONEERR_INVALBUTTONSTATE
The button states parameter is invalid.
PHONEERR_INVALDATAID
The specified data identifier is invalid.
PHONEERR_INVALDEVICECLASS
The specified phone does not support the indicated device class.
PHONEERR_INVALHOOKSWITCHDEV
The hookswitch device parameter is invalid.
PHONEERR_INVALHOOKSWITCHMODE
The hookswitch mode parameter is invalid.
PHONEERR_INVALLAMPMODE
The specified lamp mode parameter is invalid.
PHONEERR_INVALPARAM
A parameter, such as a row or column value or a window handle, is invalid or out of range.
PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.
PHONEERR_INVALPHONESTATE
The phone device is not in a valid state for the requested operation.
PHONEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.
PHONEERR_INVALPRIVILEGE
The dwPrivilege parameter is invalid.
PHONEERR_INVALRINGMODE
The ring mode parameter is invalid.
PHONEERR_NODEVICE
The specified device identifier, which was previously valid, is no longer accepted because the associated device has been removed from the system since TAPI was last initialized.
PHONEERR_NODRIVER
The telephone service provider for the specified device found that one of its components is missing or corrupt in a way that was not detected at initialization time. The user should be advised to use the Telephony Control Panel to correct the problem.
PHONEERR_NOMEM
Insufficient memory to complete the requested operation, or unable to allocate or lock memory.
PHONEERR_NOTOWNER
The application does not have owner privilege to the specified phone device.
PHONEERR_OPERATIONFAILED
The operation failed for an unspecified reason.
PHONEERR_OPERATIONUNAVAIL
The operation is not available.
PHONEERR_REINIT
If TAPI reinitialization has been requested, for example as a result of adding or removing a telephony service provider, then phoneInitialize, phoneInitializeEx or phoneOpen requests are rejected with this error until the last application shuts down its usage of the API (using phoneShutdown), at which time the new configuration becomes effective and applications are once again permitted to call phoneInitialize or phoneInitializeEx.
PHONEERR_RESOURCEUNAVAIL
The operation cannot be completed because of resource overcommitment.
PHONEERR_STRUCTURETOOSMALL
The specified phone caps structure is too small.
PHONEERR_UNINITIALIZED
The operation was invoked before any application called phoneInitialize, phoneInitializeEx.

The values 0xC0000000 through 0xFFFFFFFF are available for device-specific extensions; the values 0x80000000 through 0xBFFFFFFF are reserved; and 0x00000000 through 0x7FFFFFFF are used as request identifiers.

If an application gets an error return that it does not specifically handle (such as an error defined by a device-specific extension), it should treat the error as a PHONEERR_OPERATIONFAILED (for an unspecified reason).

See Also

phoneInitialize, phoneInitializeEx, phoneOpen, phoneShutdown


PHONEFEATURE_ Constants

The PHONEFEATURE_ constants list the operations that can be invoked on a phone using this API. Each of the PHONEFEATURE_ values correspond to a TAPI function with an identical or similar name.

PHONEFEATURE_GETBUTTONINFO (0x00000001)
PHONEFEATURE_GETDATA (0x00000002)
PHONEFEATURE_GETDISPLAY (0x00000004)
PHONEFEATURE_GETGAINHANDSET (0x00000008)
PHONEFEATURE_GETGAINSPEAKER (0x00000010)
PHONEFEATURE_GETGAINHEADSET (0x00000020)
PHONEFEATURE_GETHOOKSWITCHHANDSET (0x00000040)
PHONEFEATURE_GETHOOKSWITCHSPEAKER (0x00000080)
PHONEFEATURE_GETHOOKSWITCHHEADSET (0x00000100)
PHONEFEATURE_GETLAMP (0x00000200)
PHONEFEATURE_GETRING (0x00000400)
PHONEFEATURE_GETVOLUMEHANDSET (0x00000800)
PHONEFEATURE_GETVOLUMESPEAKER (0x00001000)
PHONEFEATURE_GETVOLUMEHEADSET (0x00002000)
PHONEFEATURE_SETBUTTONINFO (0x00004000)
PHONEFEATURE_SETDATA (0x00008000)
PHONEFEATURE_SETDISPLAY (0x00010000)
PHONEFEATURE_SETGAINHANDSET (0x00020000)
PHONEFEATURE_SETGAINSPEAKER (0x00040000)
PHONEFEATURE_SETGAINHEADSET (0x00080000)
PHONEFEATURE_SETHOOKSWITCHHANDSET (0x00100000)
PHONEFEATURE_SETHOOKSWITCHSPEAKER (0x00200000)
PHONEFEATURE_SETHOOKSWITCHHEADSET (0x00400000)
PHONEFEATURE_SETLAMP (0x00800000)
PHONEFEATURE_SETRING (0x01000000)
PHONEFEATURE_SETVOLUMEHANDSET (0x02000000)
PHONEFEATURE_SETVOLUMESPEAKER (0x04000000)
PHONEFEATURE_SETVOLUMEHEADSET (0x08000000)


PHONEHOOKSWITCHDEV_ Constants

The PHONEHOOKSWITCHDEV_ bit-flag constants describe various audio I/O devices each with its own hookswitch controllable from the computer.

PHONEHOOKSWITCHDEV_HANDSET
This is the ubiquitous, handheld, ear- and mouthpiece.
PHONEHOOKSWITCHDEV_SPEAKER
This is a built-in loudspeaker and microphone. This could also be an externally connected adjunct speaker to the telephone set.
PHONEHOOKSWITCHDEV_HEADSET
This is a headset connected to the phone set.

No extensibility. All 32 bits are reserved.

These constants are used in the PHONECAPS data structure to indicate the hookswitch device capabilities of a phone device. The PHONESTATUS structure reports the state of the phone's hookswitch devices. The function phoneSetHookSwitch and phoneGetHookSwitch use it as a parameter to select the phone's I/O device.


PHONEHOOKSWITCHMODE_ Constants

The PHONEHOOKSWITCHMODE_ bit-flag constants describe the microphone and speaker components of a hookswitch device.

PHONEHOOKSWITCHMODE_ONHOOK
The device's microphone and speaker are both onhook.
PHONEHOOKSWITCHMODE_MIC
The device's microphone is active, the speaker is mute.
PHONEHOOKSWITCHMODE_SPEAKER
The device's speaker is active, the microphone is mute.
PHONEHOOKSWITCHMODE_MICSPEAKER
The device's microphone and speaker are both active.
PHONEHOOKSWITCHMODE_UNKNOWN
The device's hookswitch mode is currently unknown.

No extensibility. All 32 bits are reserved.

These constants are used to provide an individual level of control over the microphone and speaker components of a phone device.


PHONEINITIALIZEEXOPTION_ Constants

The PHONEINITIALIZEEXOPTION_ constants specify which event notification mechanism to use when initializing a session.

PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW
The application desires to use the Hidden Window event notification mechanism.
PHONEINITIALIZEEXOPTION_USEEVENT
The application desires to use the Event Handle event notification mechanism.
PHONEINITIALIZEEXOPTION_USECOMPLETIONPORT
The application desires to use the Completion Port event notification mechanism.

See phoneInitializeEx for further details on the operation of these options.


PHONELAMPMODE_ Constants

The PHONELAMPMODE_ bit-flag constants describe various ways in which a phone's lamp can be lit.

PHONELAMPMODE_DUMMY
This value is used to describe a button/lamp position that has no corresponding lamp.
PHONELAMPMODE_OFF
The lamp is off.
PHONELAMPMODE_STEADY
Steady means the lamp is continuously lit.
PHONELAMPMODE_WINK
Wink means normal rate on and off.
PHONELAMPMODE_FLASH
Flash means slow on and off.
PHONELAMPMODE_FLUTTER
Flutter means fast on and off.
PHONELAMPMODE_BROKENFLUTTER
Broken flutter is the superposition of flash and flutter.
PHONELAMPMODE_UNKNOWN
The lamp mode is currently unknown.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Where the exact on and off cadences can differ across phone sets from different vendors, mapping of actual lamp lighting patterns for most phones onto the values listed above should be straightforward.


PHONEPRIVILEGE_ Constants

The PHONEPRIVILEGE_ bit-flag constants describe the various ways in which a phone device can be opened.

PHONEPRIVILEGE_MONITOR
An application that opens a phone device with the monitor privilege is informed about events and state changes occurring on the phone. The application cannot invoke any operations on the phone device that would change its state, so only status operations can be invoked. Multiple applications can monitor a phone device at any given time.
PHONEPRIVILEGE_OWNER
An application that opens a phone device with the owner privilege is allowed to change the state of the lamps, ringer, display, hookswitch, and data blocks of the phone. Opening a phone device in owner mode also provides monitoring of the phone device. Only one application is allowed to be the owner of a phone device at any given time.

No extensibility. All 32 bits are reserved.


PHONESTATE_ Constants

The PHONESTATE_ bit-flag constants describe various status items for a phone device.

PHONESTATE_OTHER
Phone-status items other than those listed below have changed. The application should check the current phone status to determine which items have changed.
PHONESTATE_CONNECTED
The connection between the phone device and TAPI was just made. This happens when TAPI is first invoked or when the wire connecting the phone to the PC is plugged in with TAPI active.
PHONESTATE_DISCONNECTED
The connection between the phone device and TAPI was just broken. This happens when the wire connecting the phone set to the PC is unplugged while TAPI is active.
PHONESTATE_OWNER
The number of owners for the phone device.
PHONESTATE_MONITORS
The number of monitors for the phone device.
PHONESTATE_DISPLAY
The display of the phone has changed.
PHONESTATE_LAMP
A lamp of the phone has changed.
PHONESTATE_RINGMODE
The ring mode of the phone has changed.
PHONESTATE_RINGVOLUME
The ring volume of the phone has changed.
PHONESTATE_HANDSETHOOKSWITCH
The handset hookswitch state has changed.
PHONESTATE_HANDSETVOLUME
The handset's speaker volume setting has changed.
PHONESTATE_HANDSETGAIN
The handset's microphone gain setting has changed.
PHONESTATE_SPEAKERHOOKSWITCH
The speakerphone's hookswitch state has changed.
PHONESTATE_SPEAKERVOLUME
The speakerphone's speaker volume setting has changed.
PHONESTATE_SPEAKERGAIN
The speakerphone's microphone gain setting state has changed.
PHONESTATE_HEADSETHOOKSWITCH
The headset's hookswitch state has changed.
PHONESTATE_HEADSETVOLUME
The headset's speaker volume setting has changed.
PHONESTATE_HEADSETGAIN
The headset's microphone gain setting has changed.
PHONESTATE_SUSPEND
The application's use of the phone is temporarily suspended.
PHONESTATE_RESUME
The application's use of the phone device is resumed after having been suspended for some time.
PHONESTATE_DEVSPECIFIC
The phone's device-specific information has changed.
PHONESTATE_REINIT
Items have changed in the configuration of phone devices. To become aware of these changes (as for the appearance of new phone devices), the application should reinitialize its use of TAPI.
PHONESTATE_CAPSCHANGE
Indicates that, due to configuration changes made by the user or other circumstances, one or more of the members in the PHONECAPS structure have changed. The application should use phoneGetDevCaps to read the updated structure. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version will receive PHONE_STATE messages specifying PHONESTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI to obtain the updated information.
PHONESTATE_REMOVED
Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A PHONE_STATE message with this value will normally be immediately followed by a PHONE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized will result in PHONEERR_NODEVICE being returned to the application. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI will pass it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version will not receive any notification.

No extensibility. All 32 bits are reserved.

See Also

PHONE_CLOSE, PHONE_STATE, PHONECAPS, phoneGetDevCaps


PHONESTATUSFLAGS_ Constants

The PHONESTATUSFLAGS_ bit-flag constants describe a variety of phone device status information.

PHONESTATUSFLAGS_CONNECTED
Specifies whether the phone is currently connected to TAPI. TRUE if connected, FALSE otherwise.
PHONESTATUSFLAGS_SUSPENDED
Specifies whether TAPI's manipulation of the phone device is suspended. TRUE if suspended, FALSE otherwise. An application's use of a phone device can be temporarily suspended when the switch wants to manipulate the phone in a way that cannot tolerate interference from the application.

No extensibility. All 32 bits are reserved.


STRINGFORMAT_ Constants

The STRINGFORMAT_ enumeration constants describe different string formats.

STRINGFORMAT_ASCII
Specifies standard ASCII character format using one byte per character.
STRINGFORMAT_DBCS
Specifies standard DBCS character format using one or two bytes per character.
STRINGFORMAT_UNICODE
Specifies standard Unicode character format using two bytes per character.
STRINGFORMAT_BINARY
This is an array of unsigned characters; could be used for numeric values.

No extensibility. All 32 bits are reserved.


Assisted Telephony Constants

The following constants are used by Assisted Telephony.


TAPI Error Values

TAPIERR_INVALDESTADDRESS
The pointer to the destination address is not valid, is NULL, or the destination address string is too long.
TAPIERR_INVALPOINTER
The pointer does not reference a valid memory location. One or more of the pointers lpszDestAddress, lpszAppName, lpszCalledParty, or lpszComment have been specified but are invalid.
TAPIERR_NOREQUESTRECIPIENT
No recipient application is available to handle the request. The user should start the recipient application and try again.
TAPIERR_REQUESTFAILED
The request failed for unspecified reasons.
TAPIERR_REQUESTQUEUEFULL
A recipient application is active, but the request queue is full or there is insufficient memory to expand the queue. The application can try again later.

Any other TAPIERR_ values are nonfunctional in Win32-based applications and must not be used.


TAPI Device Classes

A device class is a group of related physical devices or device drivers through which applications send and receive the information or data that makes up a call. Every device class has a device class name that uniquely identifies the class, and provides information about the programming interface and commands that can be used to open and communicate with the devices in the class.

The Telephony Application Programming Interface (TAPI) associates devices from one or more device classes to each line or phone device. You access one of these devices by retrieving the device identifier for the device using the lineGetID or phoneGetID function. You supply the device class name, and the function returns the specific port name, device name, device handle, or device identifier that you need to open and access the device. The format of the information returned depends on the device class and is described in subsequent topics of this section.

Note The device identifier definitions apply to 16-bit and 32-bit TAPI. In some cases, the datatype of a media handle in the device identifier definition may be different from that specified by the Microsoft® Windows® operating system version 3.x or Microsoft® Win32® APIFor example, Windows version 3.x and Win32 define wave device identifiers with the UINT type, but TAPI defines this device identifier with the DWORD type. In such cases, you should cast the media handle to the appropriate datatype when using it with the Windows version 3.x or Win32 API.

You also use device class names with the lineConfigDialog and phoneConfigDialog functions to enable the user to set configuration options for the given device, with the lineGetIcon and phoneGetIcon functions to retrieve an icon to represent the given device, and with the lineGetDevConfig and lineSetDevConfig functions to directly retrieve and set configuration options for the given device.

The following list shows device class names.

Device Class Name | Description
comm | Communications port.
comm/datamodem | Modem through a communications port.
comm/datamodem/portname | Name of the device to which a modem is connected.
wave/in | Wave audio device (input only).
wave/out | Wave audio device (output only).
midi/in | Midi sequencer (input only).
midi/out | Midi sequencer (output only).
tapi/line | Line device.
tapi/phone | Phone device.
ndis | Network device.
tapi/terminal | Terminal device.

Note These names are not case sensitive; you can use any combination of uppercase and lowercase letters.

Additional device classes and device class names may be available on a given system. In general, if a device does not belong to one of the default device classes, the manufacturer typically defines a new device class and assigns a unique device class name. Check the documentation for the device to determine what additional device classes are available for it. Note, however, that although the device class and media mode are related, they are not the same. A media mode describes call information format , and a device class defines the programming interface used to manage that information. So, even if a manufacturer defines a new media mode, it is not necessarily true that the manufacturer also needs to define a new device class to support the mode.

The format of the configuration data used with the lineSetDevConfig and lineGetDevConfig functions also depends on the device class. In general, you use lineGetDevConfig to save a copy of the current device configuration data and then later use lineSetDevConfig with the saved configuration data to restore the device configuration to the previous state. This is a convenient way to temporarily change the configuration without requiring the user to manually restore it to the previous state. Because the exact format of the device configuration data may be different with each service provider, you should not use lineSetDevConfig and lineGetDevConfig to manipulate the device configuration data directly. Some formats are provided only for information.


comm

The comm device class consists of communications ports. You access these devices by using the Win32 file and communications functions.

The lineGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_ASCII value and appending a null-terminated string that specifies the name of the communication device (such as the modem name).


comm/datamodem

The comm/datamodem device class consists of datamodem devices. You access these devices by using the Win32 file and communications functions. Devices in this class are associated with line devices that support the LINEMEDIAMODE_DATAMODEM media mode, which is specified in the dwMediaModes member of the LINEDEVCAPS structure for the line device.

The lineGetID function fills a VARSTRING structure, setting dwStringFormat to the STRINGFORMAT_BINARY value and appending these additional members:

HANDLE hComm;            // Win32 file handle to data modem
CHAR   szDeviceName[1];  // name of data modem

The hComm member is the handle of the open communications port. This member is NULL if the port is not yet open or if the dwSelect parameter of lineGetID is not the LINECALLSELECT_CALL value. If a call is active, the service provider typically opens the port itself to get direct control of the communications hardware, but is only required to return a valid handle if the line is connected. The service provider opens the port using the FILE_FLAG_OVERLAPPED value and then configures the port using the settings specified by the lineSetDevConfig function. You can set additional configuration options for the device by using Win32 functions with the returned handle.

The szDeviceName member is a null-terminated ASCII string that specifies the name of the communications port associated with the line, address, or call.

If hComm is a valid handle, you can use it in subsequent calls to Win32 file functions, such as ReadFile and WriteFile, to send and receive data on the call. When you are finished using the communications port and preferably before you use the lineDeallocateCall function to deallocate the call, you must close the port by using the CloseHandle function.

When using the lineGetDevConfig and lineSetDevConfig functions, some service providers require that the configuration data for this device class have the following format:

typedef struct  tagDEVCFG  {
  DEVCFGHDR   dfgHdr;
  COMMCONFIG  commconfig;
} DEVCFG, *PDEVCFG, FAR* LPDEVCFG;

// Device setting information
typedef struct  tagDEVCFGDR  {
  DWORD       dwSize;
  DWORD       dwVersion;
  WORD        fwOptions;
  WORD        wWaitBong;
} DEVCFGHDR;

The following is device configuration information for use with the lineGetDevConfig and lineSetDevConfig functions.

dwSize
Sum of the size of the DEVCFGHDR structure and the actual size of COMMCONFIG structure.
dwVersion
Version number of the Unimodem DevConfig structure. This member can be MDMCFG_VERSION (0x00010003).
dwOptions
Option flags that appear on the Unimodem Option page. This member can be a combination of these values:
TERMINAL_PRE (1)
Displays the pre-terminal screen.
TERMINAL_POST (2)
Displays the post-terminal screen.
MANUAL_DIAL (4)
Dials the phone manually, if capable of doing so.
LAUNCH_LIGHTS (8)
Displays the modem tray icon.

Only the LAUNCH_LIGHTS value is set by default

WWaitBong
Number of seconds (in two seconds granularity) to replace the wait for credit tone ($).
Commconfig
COMMCONFIG structure that can be used with the Win32 communications and modem configuration functions.


comm/datamodem/portname

The comm/datamodem/portname device class consists of the device names to which modems are attached. When this device name is specified in a call to the lineGetID function, the function fills the VARSTRING structure with a null-terminated ANSI (not Unicode) string specifying the name of the port to which the specified modem is attached, such as "COM1\0". This is intended primarily for identification purposes in the user interface, but could be used under some circumstances to open the device directly, bypassing the service provider (if the service provider does not already have the device open itself). If there is no port associated with the device, a null string ("\0") is returned in the VARSTRING structure (with a string length of 1).


wave/in

The wave/in device class consists of audio devices for low-level wave audio input. You access these devices by using the wave functions, which are described in the Microsoft Platform SDK. Devices in this class are associated with line devices that support the LINEMEDIAMODE_AUTOMATEDVOICE media modem, which is specified in the dwMediaModes member of the LINEDEVCAPS structure for the line device.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD DeviceId;  // identifier of audio device

The DeviceId member is the identifier of a closed audio device. You use this identifier in a call to the waveInOpen function to open the device for input. You can use the resulting device handle to record digitized audio data from the line or phone device.

Although a "wave" device class also exists for low-level wave audio devices, you should always use the wave/in device class for low-level wave input.


wave/out

The wave/out device class consists of audio devices for low-level wave audio output. You access these devices by using the wave functions, which are described in the Platform SDK. Devices in this class are associated with line devices that support the LINEMEDIAMODE_AUTOMATEDVOICE media mode, which is specified in the dwMediaModes member of the LINEDEVCAPS structure for the line device.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD DeviceId;  // identifier of audio device

The DeviceId member is the identifier of a closed audio device. You use this identifier in a call to the waveOutOpen function to open the device for output. You can use the resulting device handle to play digitized audio data at the line or phone device.

Although a "wave" device class also exists for low-level wave audio devices, you should always use the wave/out device class for low-level wave output.


midi/in

The midi/in device class consists of MIDI sequencers that are used for input. You access these devices by using the MIDI functions, which are described in the Platform SDK.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD DeviceId;  // identifier of MIDI device

The DeviceId member is the identifier of a closed MIDI device. You use this identifier in a call to the midiInOpen function to open the device for input. You can use the resulting device handle to record MIDI data from the line or phone device.


midi/out

The midi/out device class consists of MIDI sequencers that are used for output. You access these devices by using the MIDI functions, which are described in the Platform SDK.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD DeviceId;  // identifier of MIDI device

The DeviceId member is the identifier of a closed MIDI device. You use this identifier in a call to the midiOutOpen function to open the device for output. You can use the resulting device handle to play MIDI data at the line or phone device.


tapi/line

The tapi/line device class consists of all line devices. You access these devices using the TAPI line functions.

The lineGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member.

DWORD dwDeviceI;  // line device identifier

The dwDeviceId member is the identifier of the line device associated with the line handle given by lineGetID.

The phoneGetID function also fills a VARSTRING structure, setting dwStringFormat to STRINGFORMAT_BINARY and appending this additional member:

DWORD adwDeviceIds[];  // array of line device identifiers

The adwDeviceIds member is an array containing the device identifiers of all line devices that are associated with the phone device. If there are no associated line devices, phoneGetID returns the PHONEERR_INVALDEVICECLASS value.


tapi/phone

The tapi/phone device class consists of all phone devices. You access these devices by using the TAPI phone functions.

The phoneGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD dwDeviceI;  // phone device identifier

The dwDeviceId member is the identifier of the phone device associated with the phone handle given by phoneGetID.

The lineGetID function also fills a VARSTRING structure, setting dwStringFormat to STRINGFORMAT_BINARY and appending this additional member:

DWORD adwDeviceIds[];  // array of phone device identifiers

The adwDeviceIds member is an array containing the device identifiers of all phone devices that are associated with the given line device. If there are no associated phone devices, lineGetID returns the LINEERR_INVALDEVICECLASS value.


ndis

The ndis device class consists of devices that can be associated with network driver interface specification (NDIS) media access control (MAC) drivers to support network communications. You access these devices by using functions.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending these additional members:

HANDLE  hDevice;          // NDIS connection identifier
CHAR    szDeviceType[1];  // name of device

The hDevice member is the identifier to pass to a MAC, such as the asynchronous MAC for dial-up networking, to associate a network connection with the call/modem connection. The szDeviceType member is a null-terminated ASCII string specifying the name of the device associated with the identifier.


tapi/terminal

The tapi/terminal device class consists of the phone devices associated with each terminal on a line or the terminal on each line associated with a phone device. You access these devices by using the TAPI line or phone functions.

The lineGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD adwDeviceId[];  // array of phone device identifiers

The adwDeviceId member is an array of phone device identifiers. There is one array element for each terminal specified by the dwNumTerminals member in the LINEDEVCAPS structure for the given line device. Each element specifies the identifier of the phone device associated with the corresponding terminal on the line. If there is no phone device associated with a terminal, the element is set to –1 (0xFFFFFFFF).

The phoneGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD adwTerminalID[];  // array of terminal identifiers

The adwTerminalID member is an array of terminal identifiers. There is one array element for each line device identifier specified by the lineInitialize or lineInitializeEx function. Each array element contains the terminal identifier associated with the phone device for the given line device. If there is no phone device, the element is set to –1 (0xFFFFFFFF). The terminal identifiers range in value from zero to one less than the number specified by the dwNumTerminals member in the LINEDEVCAPS structure.


TAPI Client Management

Microsoft TAPI Client Management is a programming interface that extends the Microsoft Telephony API (TAPI) to a full client/server model. By extending TAPI, you can develop call center control applications.

In addition to extending TAPI, TAPI Client Management can itself be extended to allow third parties to implement additional administrative features. These features can include, but are not restricted to:

  • Client device privileges
  • Phone number verification
  • Least cost routing number modification


Overview of TAPI Client Management

TAPI versions 2.0 and earlier did not contain TAPI Client Management, and a user had access only to TAPI devices (telephone lines, modems, phones, and so on) that were physically attached to the computer. There was no easy way to let a user have access to only a single line in a private branch exchange (PBX) system.

TAPI Client Management enables TAPI (versions 2.0 and later) to be a viable platform for a PBX through the following telephony client/server support and administration features:

  • Remote SP, a TAPI service provider that enables users to have access to remote TAPI devices
  • Administrative features that allow third parties to perform telephony administrative tasks on telephony client requests


Remote SP

Remote SP is a TAPI service provider that enables clients to have access to TAPI devices on a telephony server. Remote SP resides on the client machine, where it appears as a service provider to TAPI. When a TAPI request is made through Remote SP, it communicates with the telephony server to service the request.


Limitations

The developer should be aware of some current user interface (UI) and server connection and service provider management limitations.

UI Limitations

The current implementation of Remote SP cannot manage user interfaces (UIs) spontaneously created by other service providers (on-the-fly UI), such as the Unimodem Talk/Drop dialog box. The only UI that will work with Remote SP is that which is generated by the TAPI lineConfigDialog, lineConfigDialogEdit, and phoneConfigDialog functions. Additionally, the TSPI service provider functions that generate UI (for example, TSPI_providerInstall) do not show the UI of the service provider on the server.

Server Connections and Service Provider Management Limitations

Remote SP will currently connect to only one telephony server at a time. Additionally, Remote SP will only work with one service provider at a time. This means that a particular user will only have access to TAPI devices serviced by a single service provider.

For example, if the telephony server has two service providers installed, a client of that telephony server can only have access to one or the other of the service provider's devices, but not to both.

Note A telephony server cannot be a client of another telephony server.


Remote SP Compatibility with Service Providers

The developer should be aware of the following Remote SP compatibility issues:

  • Remote SP is only compatible with TAPI version 2.0 service providers.
  • Remote SP must use the Telephony user interface SPI (TUISPI) for UI and communication between the client and telephony server.
  • The service provider that is installed on the telephony server must use the TUISPI interface for any UI it wants to display. If the service provider does not use the TUISPI interface or incorrectly assumes that its UI will display on the machine that the service provider is installed on, the service provider is incompatible with Remote SP.
  • Remote SP currently only handles call control. Any media streams must be handled by the service provider to work in a client/server environment.


Administration Tool

TAPI Client Management contains an administration application that permits a telephony administrator to grant client access to TAPI devices.


Client Management DLL in TAPI

TAPI Client Management provides the tcmsetup program, which can be used to set up a Windows NT® Server machine as a telephony server. TAPI Client Management also includes an administration tool. After a computer is enabled as a telephony server, and after the administrator runs the administration tool to configure access for clients, the server can accept TAPI requests from any other telephony client on the network.

TAPI Client Management implements the application programming interface in TAPI to allow third-party administration of TAPI client functions.

Certain TAPI APIs include hooks that allow a Client Management DLL to review and modify TAPI requests. When installed, TAPI calls these DLLs during the processing of these functions. When the DLL is called, it can:

  • Allow the function to continue
  • Allow the function to continue but modify certain parameters
  • Discontinue the function

Client Management DLLs are only installed on the telephony server. Any number of Client Management DLLs can be installed. If more than one Client Management DLL is installed, TAPI calls the DLLs sequentially, in the order in which they were installed.

For TAPI Client Management functions that have parameters that can be modified, the modified parameters are passed to each subsequent Client Management DLL. For example, assume there are two Client Management DLLs installed, and both export TAPICLIENT_LineMakeCall. While TAPI is processing a lineMakeCall request, it calls the first DLL's TAPICLIENT_LineMakeCall function. If the first DLL modifies the lpszDestAddress parameter, this modified parameter is passed to the second DLL.

If a modifiable parameter is a buffer, such as a destination address buffer or a LINECALLPARAMS buffer, the Client Management DLL must ensure that the buffer is large enough to accommodate any changes the Client Management DLL makes. It cannot make changes to the buffer and then return an error to TAPI, or unexpected behavior results in TAPI.

The following illustration shows where the TAPI Client Management DLLs fit into TAPI.


Further Considerations About Client Management DLLs

When implementing Client Management DLLs, consider the following:

  • A Client Management DLL must use the Unicode character set.
  • A Client Management DLL cannot call back into TAPI. If it requires TAPI information, it must use a separate thread or process. It must not block a call from TAPISRV while it waits for another thread or process to call into TAPI.
  • If the administrator changes the Client Management DLL list by running the server configuration application tcmsetup again, TAPI modifies its list of DLLs to accommodate the changes without needing to be restarted.
  • Administrator privileges on the telephony server bypasses the Client Management DLLs.


Setting Up the Telephony Server or Client

TAPI Client Management provides a setup application that can be used to set up a Microsoft Windows NT Server machine as a telephony server or Windows NT machine as a telephony client.

Overview of Setup

Conditions After Setup

Arguments for tcmsetup Program


Overview of Setup

The setup program, called tcmsetup, has a command line interface. The tcmsetup program can also be used to modify the existing server or client setup. You can make modifications by running the tcmsetup program and specifying new settings. Upon completion of the program, the modifications take effect.

Note The tcmsetup program must be run on the machine you are trying to set up. It cannot be used to configure machines remotely.


Conditions After Setup

After running the tcmsetup program, a set of conditions exists, determined by whether you have specified the machine as a server or client, and what action the program performed (setup or disable).

After server setup:

  • The user specified during setup is verified to be an administrator. If the user is not verified, the setup failed.
  • The user has the Log On As A Service privilege.
  • TAPISRV is set to start automatically.
  • TAPISRV is set to log on as the user specified, not as the LocalMachine account.
  • The Server subkey under the Telephony registry key is created. Any Management DLL entries are created and filled in. The DisableServer subkey is created and set to 0.

After the server is disabled:

  • TAPISRV is set to log on as the LocalMachine account.
  • TAPISRV is set to start manually.
  • The Server subkey under the Telephony registry key is deleted.
    Note The Log On As A Service privilege is not revoked.

After client setup:

  • Remote SP is installed as a service provider
    Note Setup does not copy the remotesp.tsp file or verify that the server is a valid machine name or that a server exists. It only adds Remote SP as a TAPI service provider.

After the client is removed:

  • Remote SP is removed as a service provider. The remotesp.tsp file is not deleted.


Arguments for tcmsetup Program

The tcmsetup program requires a different set of arguments for each of the following scenarios: server setup, server disable, client setup, and client disable. The following topics summarize the required arguments.


Server Setup

The server setup argument enables the server and administrative functionality.

TCMSETUP /S /N domain\username password [managementdlllist]

where:

  • /N indicates that the password is optional.
  • domain\username is the full domain and user name of an administrative network account (not a local machine account). TAPI logs on as this user on the telephony server.
  • password is the password for the administrative network account.
  • managementdlllist is the optional list of DLLs.
    Note The DLL names are delimited with " (a double quotation mark, not two single quotation marks).


Server Disable

The server disable argument disables telephony server and administrative functionality; however, TAPI still works locally on the machine.

TCMSETUP /S /D

Note Clients with Remote SP installed are not able to connect to the telephony server that has been disabled—they cannot access any devices on the telephony server.


Client Setup

The client setup argument sets up the machine as a client of the telephony server; however, it does not verify that the machine to connect to is actually a telephony server. After a machine is set up as a client, the machine can access all local TAPI devices and any remote TAPI devices that the user has access to (access that was granted by the telephony administrator). If the client machine cannot find the telephony server or if there is an error connecting to the telephony server, TAPI continues using only the local TAPI devices.

TCMSETUP /C telephony_server_name

where:

  • telephony_server_name is the machine name of the telephony server.


Client Disable

The client disable argument removes Remote SP from the machine on which it was running; however, TAPI still works locally on the machine.

TCMSETUP /C /D


TAPI Client Management Reference

This reference contains an alphabetic list of the TAPI Client Management functions, API hooks, and structures that are supported in this release of TAPI Client Management. The topic for each function, hook, or structure includes a statement about the function's purpose, the syntax, a description of the input parameters, a description of its return values, and additional remarks that can help you use the function in an application.


TAPI Client Management Functions

This section contains an alphabetic list of the TAPI Client Management functions in the Telephony API that Client Management DLLs can implement.

Note Some functions must be implemented, and those required functions are specified in their descriptions.


TAPICLIENT_ClientInitialize

The TAPICLIENT_ClientInitialize function is called when a new client attaches to the telephony server. This occurs when a client calls the lineInitialize, lineInitializeEx, phoneInitialize, or phoneInitializeEx function for the first time.

Every Client Management DLL must export TAPICLIENT_ClientInitialize.

LONG TAPICLIENT_ClientInitialize(
  LPCWSTR szDomain,
  LPCWSTR szUserName,
  LPCWSTR szMachineName,
  LPMANAGEMENTCLIENT phmClient
);

Parameters

szDomain
A NULL-terminated string containing the domain name of the new client.
szUserName
A NULL-terminated string containing the new client's user name.
szMachineName
A NULL-terminated string containing the machine name of the machine the client is connecting from.
phmClient
A pointer to an opaque handle that the DLL fills if the function succeeds. This handle is passed to the DLL in every other TAPICLIENT API to identify the client.

Return Values

Returns zero if the function succeeds; otherwise, returns one of the following values:

LINEERR_OPERATIONFAILED
LINEERR_NOMEM

Remarks

The Client Management DLL must fill in the phClient parameter with a handle that it can use to identify the client. The phClient parameter cannot be NULL if TAPICLIENT_ClientInitialize returns success.

See Also

lineInitialize, lineInitializeEx, phoneInitialize, phoneInitializeEx


TAPICLIENT_ClientShutdown

The TAPICLIENT_ClientShutdown function is called when a client detaches from the telephony server.

Every Client Management DLL must export TAPICLIENT_ClientShutdown.

LONG TAPICLIENT_ClientShutdown(
  HMANAGEMENTCLIENT hmClient
);

Parameters

hmClient
Opaque client handle created by TAPICLIENT_ClientInitialize.

Return Values

Returns zero if the function succeeds; otherwise returns one of the following values:

LINEERR_NOMEM
LINEERR_OPERATIONFAILED

See Also

TAPICLIENT_ClientInitialize


TAPICLIENT_Free

The TAPICLIENT_Free function is called just before the Client Management DLL is to be freed.

Every Client Management DLL must export TAPICLIENT_Free.

void TAPICLIENT_free()


TAPICLIENT_Load

The TAPICLIENT_Load function is called after TAPI has loaded the Client Management DLL (through a call to LoadLibrary).

Every Client Management DLL must export TAPICLIENT_Load.

LONG TAPICLIENT_Load(
  LPDWORD lpdwAPIVersion,
  DWORD dwReserved1,
  DWORD dwReserved2,
  DWORD dwReserved3
);

Parameters

lpdwAPIVersion
dwReserved1
Reserved parameter. This value is 0.

Reserved parameter. This value is 0.

dwReserved3
Reserved parameter. This value is 0.


TAPI Client Management DLL API Hooks

This section discusses TAPI Client Management DLL API hooks that are called from TAPISRV during their corresponding call to a TAPI function.

The following TAPI functions have corresponding TAPI Client Management functions:

lineAddToConference

lineBlindTransfer

lineDial

lineForward

lineGenerateDigits

lineMakeCall

lineOpen

lineRedirect

lineSetCallData

lineSetCallParams

lineSetCallPrivilege

lineSetCallTreatment

lineSetCurrentLocation

lineSetDevConfig

lineSetLineDevStatus

lineSetMediaControl

lineSetMediaMode

lineSetTerminal

phoneOpen

Note For more information on these TAPI functions, see the Microsoft TAPI Programmer's Reference in the Microsoft Platform Software Development Kit.

During a managed TAPI call, TAPI runs through the list of Client Management DLLs and calls the corresponding TAPICLIENT function in the DLL. The DLLs are called in the order that they are listed in the Client Management DLL registry key.

If a Client Management DLL returns LINEERR_STRUCTURETOOSMALL for a function, TAPI reallocates the buffer and calls the DLL again. If a DLL returns any other failure for a call, TAPI returns that failure to the client application. If the DLL call succeeds, TAPI calls the next DLL in the list.

Certain functions allow the Client Management DLL to modify a buffer. For example, TAPICLIENT_LineMakeCall allows the DLL to modify the destination address, LINECALLPARAMS structure, and the country code. If any parameter is modified during the call, the modified parameter is passed to the next DLL.

Note The DLL must not modify the buffer unless it returns success for that call. In addition, the DLL must verify that the buffer is large enough for the changes before it attempts to modify the buffer.

TAPI Client DLL does not need to implement every TAPICLIENT hook. A Client Management DLL can implement any hook it is interested in.

The following return values apply to all TAPICLIENT functions.

Return Value | Meaning
0 | Success; the client is allowed to continue with this call.
LINEERR_STRUCTURETOOSMALL | A modifiable buffer passed in is too small for the modifications.
LINEERR_BILLINGREJECTED | The destination address is not allowed.
LINEERR_INVALFEATURE | The client is not allowed to call this function (under these conditions).
LINEERR_NOMEM | There was a memory failure during normal processing of this function.
LINEERR_OPERATIONFAILED | Some failure occurred during processing of this function.


TAPICLIENT_LineAddToConference

The TAPICLIENT_LineAddToConference function is called during a call to the lineAddToConference function.

LONG TAPICLIENT_LineAddToConference(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  LPLINECALLINFO const lpConsultCallCallInfo
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
lpConsultCallCallInfo
A pointer to a LINECALLINFO structure that is filled with information about the consultation call passed to lineAddToConference.

Remarks

The lpConsultCallCallInfo parameter is passed in to give the TAPI Client Management DLL information about the call being added to the conference.

See Also

lineAddToConference, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPICLIENT_LineBlindTransfer

The TAPICLIENT_LineBlindTransfer function is called during a call to lineBlindTransfer.

LONG TAPICLIENT_LineBlindTransfer(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  LPWSTR lpszDestAddress,
  LPDWORD lpdwDestAddressSize,
  LPDWORD lpdwCountryCode
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
lpszDestAddress
Buffer containing the destination address passed in. The DLL can modify this buffer.
lpdwDestAddressSize
Pointer to a DWORD containing the size in bytes of the lpszDestAddress buffer. On entry, it contains the size of the buffer. If the buffer is not large enough for the modified destination address, the DLL fills in this parameter with the needed size.
lpdwCountryCode
Pointer to a DWORD containing the country code passed in. The DLL can modify this parameter.

See Also

lineBlindTransfer, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPICLIENT_LineDial

The TAPICLIENT_LineDial function is called during a call to the lineDial function.

LONG TAPICLIENT_LineDial(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  DWORD dwReserved,
  LPWSTR lpszDestAddress,
  LPDWORD lpdwDestAddressSize,
  LPDWORD lpdwCountryCode
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
dwReserved
Reserved. The value is 0.
lpszDestAddress
Buffer containing the destination address passed in. The DLL can modify this buffer.
lpdwDestAddressSize
Pointer to a DWORD containing the size in bytes of the lpszDestAddress buffer. On entry, it contains the size of the buffer. If the buffer is not large enough for the modified destination address, the DLL fills in this parameter with the needed size.
lpdwCountryCode
Pointer to a DWORD containing the country code passed in. The DLL can modify this parameter.

See Also

lineDial, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPICLIENT_LineForward

The TAPICLIENT_LineForward function is called during a call to the lineForward function.

LONG TAPICLIENT_LineForward(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  LPLINEFORWARDLIST lpForwardList,
  LPDWORD lpdwForwardListSize,
  LPCALLPARAMS lpCallParams,
  LPDWORD lpdwCallParamsSize
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
lpForwardList
Pointer to the forward list passed in to TAPI. This buffer can be modified by the DLL.
lpdwForwardListSize
Pointer to a DWORD containing the size in bytes of the lpForwardList buffer. On entry, it contains the size of the buffer. If the buffer is not large enough for the modified destination address, the DLL fills in this parameter with the needed size.
lpCallParams
Pointer to the LINECALLPARAMS structure passed in to TAPI. This buffer can be modified by the DLL.
lpdwCallParamsSize
Pointer to a DWORD containing the size in bytes of the lpCallParams buffer. On entry, it contains the size of the buffer. If the buffer is not large enough for the modified destination address, the DLL fills in this parameter with the needed size.

See Also

LINECALLPARAMS, lineForward, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPICLIENT_LineGenerateDigits

The TAPICLIENT_LineGenerateDigits function is called during a call to the lineGenerateDigits function.

LONG TAPICLIENT_LineGenerateDigits(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  DWORD dwReserved,
  LPWCSTR lpszDigits
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
dwReserved
Reserved. The value is 0.
lpszDigits
The digits passed in to TAPI. This buffer cannot be modified by the DLL. However, the DLL may fail the call if the digits cannot be generated.

See Also

lineGenerateDigits, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPICLIENT_LineMakeCall

The TAPICLIENT_LineMakeCall function is called during a call to the lineMakeCall function.

LONG TAPICLIENT_LineMakeCall(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  DWORD dwReserved,
  LPWSTR lpszDestAddress,
  LPDWORD lpdwDestAddressSize,
  LPDWORD lpdwCountryCode,
  LPLINECALLPARAMS lpCallParams,
  LPDWORD lpdwCallParamsSize
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
dwReserved
Reserved. The value is 0.
lpszDestAddress
Buffer containing the destination address passed in. The DLL can modify this buffer.
lpdwDestAddressSize
Pointer to a DWORD containing the size in bytes of the lpszDestAddress buffer. On entry, it contains the size of the buffer. If the buffer is not large enough for the modified destination address, the DLL fills in this parameter with the needed size.
lpdwCountryCode
Pointer to a DWORD containing the country code passed in. The DLL can modify this parameter.
lpCallParams
Pointer to the LINECALLPARAMS structure passed in to TAPI. The DLL can modify this parameter.
lpdwCallParamsSize
Pointer to a DWORD containing the size in bytes of the lpCallParams buffer. On entry, it contains the size of the buffer. If the buffer is not large enough for the modified destination address, the DLL fills in this parameter with the needed size.

See Also

LINECALLPARAMS, lineMakeCall, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPICLIENT_LineOpen

The TAPICLIENT_LineOpen function is called during a call to the lineOpen function.

LONG TAPICLIENT_LineOpen(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  DWORD dwAPIVersion,
  DWORD dwExtVersion,
  DWORD dwPrivileges,
  DWORD dwMediaModes,
  LPLINECALLPARAMS lpCallParams,
  LPDWORD lpdwCallParamsSize
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
dwAPIVersion
The API version passed in to TAPI.
dwExtVersion
The extension version passed in to TAPI.
dwPrivileges
The privileges passed in to TAPI.
dwMediaModes
The media modes passed in to TAPI.
lpCallParams
Pointer to the LINECALLPARAMS structure passed in to TAPI. The DLL can modify this parameter.
lpdwCallParamsSize
Pointer to a DWORD containing the size in bytes of the lpCallParams buffer. On entry, it contains the size of the buffer. If the buffer is not large enough for the modified destination address, the DLL fills in this parameter with the needed size.

See Also

LINECALLPARAMS, lineOpen, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPICLIENT_LineRedirect

The TAPICLIENT_LineRedirect function is called during a call to the lineRedirect function.

LONG TAPICLIENT_LineRedirect(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  LPWSTR lpszDestAddress,
  LPWSTR lpszDestAddressSize,
  LPDWORD lpdwCountryCode
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
lpszDestAddress
Buffer containing the destination address passed in. The DLL can modify this buffer.
lpdwDestAddressSize
Pointer to a DWORD containing the size in bytes of the lpszDestAddress buffer. On entry, it contains the size of the buffer. If the buffer is not large enough for the modified destination address, the DLL fills in this parameter with the needed size.
lpdwCountryCode
Pointer to a DWORD containing the country code passed in. The DLL can modify this parameter.

See Also

lineRedirect, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPICLIENT_LineSetCallData

The TAPICLIENT_LineSetCallData function is called during a call to the lineSetCallData function.

LONG TAPICLIENT_LineSetCallData(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  LPVOID lpCallData,
  DWORD dwSize
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
lpCallData
Pointer to a buffer containing the call data passed to TAPI. This buffer cannot be modified by the DLL.
dwSize
The DWORD that contains the size of lpCallData.

See Also

lineSetCallData, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPICLIENT_LineSetCallParams

The TAPICLIENT_LineSetCallParams function is called during a call to the lineSetCallParams function.

LONG TAPICLIENT_LineSetCallParams(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  DWORD dwBearerMode,
  DWORD dwMinRate,
  DWORD dwMaxRate,
  LPLINEDIALPARAMS lpDialParams
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
dwBearerMode
The bearer mode passed in to TAPI.
dwMinRate
The min rate passed in to TAPI.
dwMaxRate
The max rate passed in to TAPI.
lpDialParams
The LINEDIALPARAMS structure passed in to TAPI. The buffer can be modified.

See Also

LINEDIALPARAMS, lineSetCallParams, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPICLIENT_LineSetCallPrivilege

The TAPICLIENT_LineSetCallPrivilege function is called during a call to the lineSetCallPrivilege function.

LONG TAPICLIENT_LineSetCallPrivilege(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  DWORD dwCallPrivilege
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
dwCallPrivilege
The call privilege passed in to TAPI.

See Also

lineSetCallPrivilege, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPICLIENT_LineSetCallTreatment

The TAPICLIENT_LineSetCallTreatment function is called during a call to the lineSetCallTreatment function.

LONG TAPICLIENT_LineSetCallTreatment(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  DWORD dwCallTreatment
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
dwCallTreatment
The call treatment passed in to TAPI.

See Also

lineSetCallTreatment, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPICLIENT_LineSetCurrentLocation

The TAPICLIENT_LineSetCurrentLocation function is called during a call to the lineSetCurrentLocation function.

LONG TAPICLIENT_LineSetCurrentLocation(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  DWORD dwLocation
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
dwLocation
The location passed in to TAPI.

See Also

lineSetCurrentLocation, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPICLIENT_LineSetDevConfig

The TAPICLIENT_LineSetDevConfig function is called during a call to the lineSetDevConfig function.

LONG TAPICLIENT_LineSetDevConfig(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  LPVOID lpDevConfig,
  LPDWORD lpdwSize,
  LPCWCSTR lpszDeviceClass
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
lpDevConfig
The device configuration buffer passed in to TAPI. This buffer can be modified by the DLL.
lpdwSize
Pointer to a DWORD containing the size in bytes of the lpDevConfig buffer. On entry, it contains the size of the buffer. If the buffer is not large enough for the modified destination address, the DLL fills in this parameter with the needed size.
lpszDeviceClass
String that specifies the device class of the device whose configuration is to be set.

See Also

lineSetDevConfig, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPICLIENT_LineSetLineDevStatus

The TAPICLIENT_LineSetLineDevStatus function is called during a call to the lineSetLineDevStatus function.

LONG TAPICLIENT_LineSetLineDevStatus(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  DWORD dwStatusToChange,
  DWORD fStatus
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
dwStatusToChange
The status to change passed in to TAPI.
fStatus
The status flag passed in to TAPI.

See Also

lineSetLineDevStatus, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPICLIENT_LineSetMediaControl

The TAPICLIENT_LineSetMediaControl function is called during a call to the lineSetMediaControl function.

LONG TAPICLIENT_LineSetMediaControl(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  LPLINEMEDIACONTROLDIGIT const lpDigitList,
  DWORD dwDigitNumEntries,
  LPLINEMEDIACONTROLMEDIA const lpMediaList,
  DWORD dwMediaNumEntries,
  LPLINEMEDIACONTROLTONE const lpToneList,
  DWORD dwToneNumEntries,
  LPLINEMEDIACONTROLCALLSTATE const lpCallstateList,
  DWORD dwCallstateNumEntries
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
lpDigitList
Digit list buffer passed in to TAPI.
dwDigitNumEntries
The number of entries in the digit list.
lpMediaList
The media list buffer passed in to TAPI.
dwMediaNumEntries
The number of entries in the media list.
lpToneList
The tone list buffer passed in to TAPI.
dwToneNumEntries
The number of entries in the tone list.
lpCallstateList
The call state list buffer passed in to TAPI.
dwCallstateNumEntries
The number of entries in the call state list.

See Also

lineSetMediaControl, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPICLIENT_LineSetMediaMode

The TAPICLIENT_LineSetMediaMode function is called during a call to the lineSetMediaMode function.

LONG TAPICLIENT_LineSetMediaMode(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  DWORD dwMediaModes
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
dwMediaModes
The media modes passed in to TAPI.

See Also

lineSetMediaMode, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPICLIENT_LineSetTerminal

The TAPICLIENT_LineSetTerminal function is called during a call to the lineSetTerminal function.

LONG TAPICLIENT_LineSetTerminal(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  DWORD dwTerminalModes,
  DWORD dwTerminalID,
  BOOL bEnable
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
dwTerminalModes
The terminal modes passed in to TAPI.
dwTerminalID
The terminal identifier passed in to TAPI.
bEnable
The bEnable parameter passed in to TAPI.

See Also

lineSetTerminal, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPICLIENT_PhoneOpen

The TAPICLIENT_PhoneOpen function is called during a call to the phoneOpen function.

LONG TAPICLIENT_PhoneOpen(
  HMANAGEMENTCLIENT hmClient,
  LPTAPIPERMANENTID lpPermanentID,
  DWORD dwAPIVersion,
  DWORD dwExtVersion,
  DWORD dwPrivileges
);

Parameters

hmClient
Opaque handle to the client that the Client Management DLL returned in TAPICLIENT_ClientInitialize.
lpPermanentID
The TAPIPERMANENTID identifier of the device.
dwAPIVersion
The API version passed in to TAPI.
dwExtVersion
The extension version passed in to TAPI.
dwPrivileges
The privileges passed in to TAPI.

See Also

phoneOpen, TAPICLIENT_ClientInitialize, TAPIPERMANENTID


TAPI Client Management Structures

TAPI Client Management introduces one new structure, TAPIPERMANENTID.


TAPIPERMANENTID

The TAPIPERMANENTID structure uniquely identifies a TAPI line device or phone device.

typedef struct tapipermanentid_tag {
    DWORD  dwProviderID;
    DWORD  dwPermanentDeviceID;
} TAPIPERMANENTID, *LPTAPIPERMANENTID;

Members

dwProviderID
The provider identifier of the provider that owns the device.
dwPermanentDeviceID
The permanent line identifier or phone identifier of the device. This identifier can be obtained from the TAPI LINEDEVCAPS structure for a line device or the TAPI PHONECAPS structure for a phone device.

See Also

LINEDEVCAPS, PHONECAPS, TAPICLIENT_LineAddToConference, TAPICLIENT_LineBlindTransfer, TAPICLIENT_LineForward, TAPICLIENT_LineGenerateDigits, TAPICLIENT_LineMakeCall, TAPICLIENT_LineOpen, TAPICLIENT_LineRedirect, TAPICLIENT_LineSetCallData, TAPICLIENT_LineSetCallParams, TAPICLIENT_LineSetCallPrivilege, TAPICLIENT_LineSetCallTreatment, TAPICLIENT_LineSetCurrentLocation, TAPICLIENT_LineSetDevConfig, TAPICLIENT_LineSetLineDevStatus, TAPICLIENT_LineSetMediaControl, TAPICLIENT_LineSetMediaMode, TAPICLIENT_LineSetTerminal, TAPICLIENT_PhoneOpen


Legal Information

Telephony Service Provider Interface (TSPI) Programmer's Reference

This is a preliminary document and may be changed substantially prior to final commercial release. This document is provided for informational purposes only and Microsoft makes no warranties, either express or implied, in this document. Information in this document is subject to change without notice. The entire risk of the use or the results of the use of this document remains with the user. The names of companies, products, people, characters, and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted. Complying with all applicable copyright laws is the responsibility of the user. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Microsoft Corporation.

Portions of this document specify and accompany software that is still in development. Some of the information in this documentation may be inaccurate or may not be an accurate representation of the functionality of final documentation or software. Microsoft assumes no responsibility for any damages that might occur directly or indirectly from these inaccuracies.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 1995–1998 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, MS, Windows, Windows NT, and Win32 are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries.

Other product and company names mentioned herein may be the trademarks of their respective owners.


Using the TSPI 2.1 Programmer's Reference

This document describes the Telephony Service Provider Interface (TSPI) and explains how to create service providers for the Microsoft® Windows® family of operating systems that support the Microsoft Win32® application programming interface (API). This TSPI reference discusses many basic concepts, such as the telephony model and TAPI, that are necessary to successfully develop a telephony service provider.

TSPI defines the external interface of service providers that are implemented by vendors of telephony equipment. Service providers give access to vendor-specific equipment through a procedure-oriented dynamic-link library (DLL) interface. Installing a service provider allows Win32-based applications that use elements of telephony to access the corresponding telephony equipment.

This documentation assumes a familiarity with TAPI and the Telephony Application Programming Interface (TAPI) reference. The intended audience is the developer experienced with programming telephony applications for the Windows environment.


Document Overview

This documentation presents information on how to use TSPI functions, messages, structures, constants, and datatypes. The sections include:

  • Overviews, which provides an overview of TSPI. It describes basic concepts, the usage model underlying TSPI, its relation to other Win32 service provider interfaces, and an overview of the functions, messages, data structures, and device classes provided by TSPI.
  • Reference, which contains functional descriptions of the following:

    TSPI Functions, which describes service provider, line device, phone device, and callback functions

    Telephony Service Provider UI DLL Interface, TSPI UI and TUISPI service provider, line device, phone device, and callback functions

    Structures, which defines TSPI data structures.

    Messages, which contains a list of TSPI messages that notify TAPI32.DLL of the occurrence of asynchronous events.

    Constants, which provides a detailed listing of TSPI phone device constants.

    Device Classes, which describes related physical devices or device drivers through which applications send and receive the data that makes up a call.

    Service Provider Datatypes, which describes specific values passed as parameters through functions or opaque handles through structures.


What's New for TSPI Version 2.1

  • Part of the Telephony Application Programming Interface (TAPI) information set. TSPI documentation now appears in the same information set as TAPI.
  • Updated document organization. The documentation supporting TSPI is organized to parallel TAPI documentation.
  • Functions updated. Functions that are implemented in service providers for TAPI version 1.4 and earlier but were replaced by Telephony user interface SPIs (TUISPI) in version 2.0 have been annotated as obsolete. However, owing to their value for earlier TAPI versions, these functions remain in the information set as well as cross-reference to their replacements.


Service Provider Features in TAPI Version 2.0

To provide the best performance and support on the Windows NT and Windows 95 platforms, the Win32 Telephony service providers are fully implementated as 32-bit components in Win32. The following service provider features in TAPI version 2.0 are new:

  • On the Windows NT platform, TAPI 2.0 service providers must be Win32; 16-bit service providers do not run on Windows NT.
  • On the Windows 95 platform, TAPI 2.0 service providers should be Win32 but existing 16-bit Windows 3.1 and Windows 95 service providers are supported by a 16-bit compatibility layer.
  • TAPI 2.0 service providers must support version 2.0; TAPI does not provide backward compatibility for service providers supporting only data structure formats for version 1.3 or 1.4.
  • TAPI 2.0 imports service provider functions by name instead of by ordinal (as in previous versions).
  • TAPI 2.0 service providers must be fully Unicode; all strings passed as parameters to TSPI functions or returned by service providers in structures or through pointers must be in Unicode.
  • TAPI 2.0 service providers run in user mode. Kernel mode components do not have direct access to TAPI services. Service provider developers can, of course, use any appropriate mechanism to access kernel mode components, should they choose to use such an architecture.
  • TAPI 2.0 uses Telephony service provider user interface DLLs to manage and display dialog boxes. TAPI loads the DLL into the process of an application that invokes any of the service provider functions that can display a dialog.
  • TAPI 2.0 permits proxy request handlers. A handler is a full Telephony application that normally executes on a telephony server and provides services that are more appropriately implemented in an application than a driver.

Note The actual implementation of a client-server service provider for Windows NT and Windows 95, and of the server-side components (agent application, administration tools, third party call control service provider, and switch protocol link drivers) is not described in this document. See TAPI Client Management for TAPI documentation.

Functions and messages that were new or changed for TSPI version 2.0 are as follows:

Function |
TSPI_lineConditionalMediaDetection | Changed the conditions under which LINEERR_RESOURCEUNAVAIL is returned.
TSPI_lineDropNoOwner | Obsolete.
TSPI_lineDropOnClose | Obsolete.
TSPI_lineGetID | Changed. Includes an additional parameter.
TSPI_lineSetCallData | New
TSPI_lineSetCallQualityOfService | New
TSPI_lineSetCallTreatment | New
TSPI_lineSetLineDevStatus | New
TSPI_phoneGetID | Changed. Includes an additional parameter.
TSPI_providerInit | Changed
TSPI_providerShutdown | New parameter

Message |
LINE_GATHERDIGITS | Changed. Tick count added.
LINE_GENERATE | Changed. Tick count added.
LINE_MONITORDIGITS | Changed. Tick count added.
LINE_MONITORMEDIA | Changed. Tick count added.
LINE_MONITORTONE | Changed. Tick count added.
LINE_REMOVE | New
PHONE_REMOVE | New

The Telephony service provider user interface DLL provides a means of allowing user interaction within the context of the application rather than the service provider itself. TSPI version 2.0 delivered the following new functions, messages, and structures for implementation:

TSPI_providerFreeDialogInstance | New
TSPI_providerGenericDialogData | New
TSPI_providerUIIdentify | New
TUISPI_lineConfigDialog | New
TUISPI_lineConfigDialogEdit | New
TUISPI_phoneConfigDialog | New
TUISPI_providerConfig | New
TUISPI_providerGenericDialog | New
TUISPI_providerGenericDialogData | New
TUISPI_providerInstall | New
TUISPI_providerRemove | New
TUISPIDLLCALLBACK | New
LINE_CREATEDIALOGINSTANCE | New
LINE_SENDDIALOGINSTANCEDATA | New
TUISPICREATEDIALOGINSTANCEPARAMS | New


Document Conventions

This document uses the following conventions.

Convention | Description
Bold text | Bold letters indicate terms, such as function, structure, and structure member names, that you must enter exactly as shown.
ALL CAPS | All capital letters typically indicate terms, such as message and constant names, that you must enter exactly as shown.
Italic text | In introductory and explanatory text, italicized words indicate that a key term or concept is being introduced. In describing functions and messages, words in italics indicate a placeholder; you are expected to provide the actual value.
Monospaced text | Monospaced type indicates code samples, syntax, and data-structure definitions.


Overviews

This section contains overviews on telephony services, the telephony programming model, call states and events, line devices, and phone devices.


Telephony Services

Telephony is a technology that integrates computers with the telephone network. With telephony, people can use their computers to take advantage of a wide range of sophisticated communications features and services over a telephone line. The Win32 Telephony Service Provider Interface (TSPI) lets programmers develop telephony services that handle requests from applications to carry out and control communications over the telephone network.

Win32 Telephony supports both speech and data transmission, allows for a variety of terminal devices, and supports complex connection types and call-management techniques such as conference calls, call waiting, and voice mail. Telephony allows all elements of telephone usage to be controlled by applications through the Telephony Application Programming Interface (TAPI). These applications rely on the existence of service providers that support this functionality. The role of the service provider is to provide TSPI functions that carry out the tasks requested by applications using the TAPI functions.


Telephone Network Services

You can develop telephony service providers for a variety of telephone network services and technologies, including:

  • POTS (Plain Old Telephone Service) Voice and data are transmitted in analog format while in the local loop and are digitally transmitted elsewhere. Typically, one media mode per call, one channel per line.
  • ISDN (Integrated Services Digital Network) Transmitted digitally. Speeds of up to 128 Kbps on Basic Rate Interface (BRI-ISDN) lines and much higher on Primary Rate Interface (PRI-ISDN) lines. At least three channels and as many as 32 channels, for simultaneous, independently operated transmission of voice and data. International standard.
  • T1/E1 Transmitted digitally. T1 is a transmission link with a capacity of 1.544 Mbps, typically used for connecting networks across remote distances. In Europe T1 is called E1.
  • Switched 56 Signaling at 56 Kbps over dial-up telephone lines, but requires special equipment. Limited to calls to other specially equipped facilities.
  • CENTREX Centralized network services through regular telephone lines and using telephone company equipment. No special equipment required.
  • Digital PBXs (private branch exchanges) and key systems Voice and data transmitted on private telephone systems using proprietary interfaces.


Architectural Overview

Win32 Telephony is a full, 32-bit implementation of the original 16-bit Windows Telephony application and service provider interface. Other than components provided for backward compatibility, all components of Win32 Telephony, including service providers, are implemented in 32 bits. The following figure illustrates the architecture of Win32 Telephony on the Windows operating systems.

Existing 16-bit applications link to TAPI. In Windows 3.1 and Windows 95, TAPI is the core of Windows Telephony, but in Windows NT, TAPI is simply a thunk layer to map 16-bit addresses to 32-bit addresses, and pass requests along to tapi32.dll.

Existing 32-bit applications link to tapi32.dll. In Windows 95, tapi32.dll is a thunk layer to TAPI. In Windows NT (and future releases of the Windows 95 platform), tapi32.dll is a thin marshaling layer, that transfers function requests to tapisrv.exe and, when needed, loads and invokes service provider user interface DLLs in the application's process.

In the Win32 implementation, tapisrv.exe is the core of TAPI. It runs as a separate service process, subsuming the role played in Windows 3.1 and Windows 95 by the tapisrv.exe hidden process and TAPI itself. All telephony service providers execute in the tapisrv.exe process, eliminating the difficulties that arose in previous versions of Windows telephony caused by service providers sometimes running in the TAPIEXE context, and sometimes in the context of an individual application. Service providers can create threads in the TAPISRV context as needed to do their work, and be confident that none of the resources they create will be destroyed by the exit of any individual application.

Underneath the telephony service provider DLL, the service provider can use any system functions or other components necessary. These functions include CreateFile and DeviceIOControl, which work with independent hardware vendor-designed kernel mode components and services, as well as standard devices such as serial and parallel ports to control external, locally attached devices. They can also access network services (such as RPC, Windows Sockets, and Named Pipes) for client/server telephony.

The Telephony service provider user interface DLL is new. This DLL is loaded by TAPI into the process of an application that invokes any of the service provider functions that can display a dialog box (for example, TSPI_lineConfigDialog). The service provider can also cause its associated UI DLL to be loaded and executed in the process of an application if the service provider needs to display UI at unexpected times, such as to display the Talk/Hang-up dialog box displayed by the Universal Modem Driver (UNIMODEM) when a data modem is used to dial an interactive voice call using TSPI_lineMakeCall (not normally considered to be a UI-generating function).

The new proxy request handler is a full telephony application that normally executes on a telephony server (the same server on which the telephony service provider is executing for the associated line devices). This architecture, rather than the WOSA service provider architecture, is used when a particular service is more appropriately implemented in an application than in a driver on the server. In this version of Win32 Telephony, the ACD Agent management functions are implemented in a proxy request handler rather than in a service provider.

The UNIMODEM driver service provider for modem control is available on Windows NT. Windows Telephony for Windows NT also includes a generic kernel mode Telephony Service Provider Interface (TSPI) mapper, known as KMDDSP, that allows service providers to be implemented as kernel mode device drivers.


Service Provider

A service provider is a dynamic-link library (DLL) that supports communications over a telephone network through a set of exported service functions. The service provider responds to telephony requests, sent to it by the TAPI, by carrying out the low-level tasks necessary to communicate over the telephone network. In this way, the service provider, in conjunction with TAPI, shields applications from the service- and technology-dependent details of the telephone network communication.

You write a service provider to extend telephony services for existing hardware or to provide telephony services for new hardware. Each service provider supports at least one hardware device, such as a fax board, an ISDN card, a telephone, or a modem. Some providers support a combination of devices. The installation utility for a service provider or the user associates a service provider with its hardware devices. Multiple service providers can be installed as long as they access different devices.

Each service provider is responsible for responding to telephony requests from TAPI to control line and phone devices. A service provider is also responsible for controlling and accessing the information exchanged over a call. To manage this information (called the media stream), the service provider must provide additional capabilities or functions. For example, a service provider that supports fax or data transmission must implement the TSPI functions that control and monitor the line over which data is sent. It must either implement functions that carry out the actual transmission of the data over the line or ensure that applications can use existing Win32 functions to carry out the transmission.

If a service provider implements its own functions to manage the media stream, it is recommended that the functions be based on standard Win32 functions, such as the communication or multimedia functions. For nonstandard or custom hardware devices, however, it may be best to develop a custom interface.

To access the actual device, a device driver is required. Although, in some cases, a service provider can contain a device-driver component, it is recommended that service providers either use existing device drivers, or develop the device driver as a separate, installable component.

The sample service provider, not intended to be a full-featured service provider, is the base on which you can develop more extensive service providers.

The variations to the standard DLL interface model that a service provider must observe are as follows:

  • Use the filename extension .tsp instead of DLL. Although, not a strict requirement, using this extension lets users change the service configuration by using the XXX utility.
  • Service providers that support interactive configuration features and wish to let them be accessed with this tool must have the .tsp file extension.


Service Provider for TAPI 2.0

Under TAPI version 2.0, a telephony service provider consists of, at a minimum, a 32-bit DLL that executes in user mode in the TAPISRV process. This DLL can create threads and synchronization objects within the TAPISRV context. If the service provider implements any user interface elements, it must also export user interface DLL functions (prefixed by TUISPI); these can be included in a single DLL along with the TSPI functions.

Because they are running within the context of a Win32 process, service providers can be re-entered in the same or different functions from separate threads. The service provider must be designed with proper synchronization mechanisms on global data and resources. For performance reasons, implementors are discouraged from requiring a single master mutex on the entire service provider, although such a mechanism can be advantageous during an interim period while porting 16-bit service provider code; TAPI provides this mutex if requested by the service provider during TSPI_providerInit. TAPI is also so that it does not call a telephony service provider function on the same thread the telephony service provider used to call the LINEEVENT, PHONEEVENT, or ASYNC_COMPLETION callbacks in TAPI. However, it is possible for the service provider to be entered on other threads while it is executing in a TAPI callback function.

Service providers using TAPI version 2.0 must support at least TSPI version 2.0, including all data structure members. TAPI will not adapt older service providers to work with newer applications.

In accordance with the Win32 standard, all TSPI functions are imported by TAPI by name, rather than by ordinal, as was the practice in previous 16-bit implementations. The performance differential, which was significant in 16-bit Windows, is very slight in Win32 and no longer justifies the relative complexity, confusion, and risk of error that is possible in requiring service providers to export TSPI functions by ordinal.

Except as noted in TSPI Functions, all strings passed into or returned by service provider functions must be in Unicode.

TAPI no longer uses the telephon.ini file for storage of telephony parameters. Service providers, like all Win32 services, must use the registry for storage of persistent private data. This data is not placed in TAPI's section of the registry, the format of which is not guaranteed to be maintained in future versions. Service providers should create their own branch under the Software key. Service providers should not directly access their registry parameters from within the context of an application (for example, directly from a TUISPI function), but should instead pass requests back to the main service provider DLL in the TAPISRV context for synchronization and processing.


Service Dependencies

You must ensure accurate listing of service dependencies among TAPI (specifically, the telephony service—tapisrv.exe), other service applications that use TAPI, and telephony service providers that use other services.

The installation program for the service application or telephony service provider must record these dependencies with the Service Control Manager.

Note Failure to list TAPI as a dependency of the service application or failure to list another service as a dependency of TAPI can result in the system hanging.

List "Telephony Service" as a dependency of any service application that initializes a TAPI line or phone function. When TAPI is a dependency of a service application, the installation program must include "Telephony Service" in the list of service names passed to the lpDependencies parameter of the CreateService function.

When another service is activated by the telephony service provider during the service provider startup (during TSPI_providerEnumDevices, TSPI_lineNegotiateTSPIVersion, or TSPI_providerInit), the service started by the telephony service provider must be listed as a dependency of the "Telephony Service." As a service that starts dynamically, TAPI starts all telephony service providers during its startup, and it is critical for the Service Control Manager to know when any service provider starts another service during telephony service provider startup.

Call the QueryServiceConfig function to determine the existing configuration of "Telephony Service", including dependencies. If the service or services started by the telephony service provider are not already included in the dependencies of the "Telephony Service", add the necessary items to the dependency list and call ChangeServiceConfig to update the dependencies.

For additional information about changing a service configuration, see the Microsoft Platform Software Development Kit.


Models

Service providers can support different models of the ways lines and phones are handled, based on how the devices are physically configured. This topic describes a selection of configurations that a service provider might support.

The computer-centric model uses a computer add-in card or an external add-on box that is connected to both the telephone network switch and the phone set. This model can easily integrate modem and fax functions, as well as the use of the telephone as an audio I/O device.

The phone-centric model connects the computer to the switch through the desktop phone set. Such phone sets typically connect to the computer through one of its serial ports. The service provider converts requests into telephony commands, such as commands based on the Hayes AT command set (ANSI/TIA/EIA-602), and sends them over the serial connection to the telephone. This configuration is limited because it generally provides only line control. The computer has no access to the media stream.

A single BRI-ISDN (Basic Rate Interface-ISDN) line could fit both the phone-centric and computer-centric models. The service provider can treat this capability in a number of ways:

  • Model the BRI line as a single line device with a pool of two B channels, allowing both channels to be combined for establishing 128 Kbps calls.
  • Model each B-channel as a separate line device and disallow the combination of the two channels into a single 128 Kbps channel.
  • Model the BRI connection as two separate line devices, each drawing up to two channels from a shared pool of two B-channels.
  • Model as three line devices: one for each of the two B-channels and one for the combination.

In the latter two models, channels can be assigned to different line devices at different times.

A LAN-based server might have multiple telephone line connections to the switch. TAPI operations invoked at any of the client computers are forwarded over the LAN to the server. The server uses third-party call control between the server and the switch to implement the client's call control requests.

This model offers a lower cost per computer for call control if the LAN is already in use, and it also offers reduced cost for media stream access if shared devices such as voice digitizers, fax and or data modems, and interactive voice response cards are installed in the server. The digitized media streams can be carried over the LAN, although real-time transfer of media may be problematic with some LAN technologies due to inconsistent throughput.

A LAN-based host can be connected to the switch using a switch-to-host link. TAPI operations invoked at any of the client computers are forwarded over the LAN to the host, which uses a third-party switch-to-host link protocol to implement the client's call control requests.

It is also possible for a private branch exchange (PBX) to be directly connected to the LAN, and for the server functions to be integrated into the PBX. Within this model, different subconfigurations are possible:

  • To provide personal telephony to each desktop, the service provider can model the PBX line associated with the computer (on a desktop) as a single line device with one channel. Each client computer has one line device available.
  • Each third-party station can be modeled as a separate line device to allow applications to control calls on other stations. (In a PBX, a station is anything to which a wire leads from the PBX). This enables the application to control calls on other stations. This solution requires that the application open each line it wants to manipulate or monitor, which is satisfactory if only a small number of lines is of interest, but can generate excessive overhead if a large number of lines is involved.
  • Model the set of all third-party stations as a single line device with one address (one phone number) assigned to it per station. Only a single device can be opened, providing monitoring and control of all addresses (all stations) on the line. To originate a call on any of these stations, the application must only specify the station's address to the function that makes the call. No extra lineOpen operations are required. However, this modeling implies that all stations have the same line-device capabilities, although their address capabilities can be different.

A potential advantage of this model is a lowered cost per computer if the LAN is already in use, but a limitation is a possible lack of media-stream access by the computers.

The computer in use need not be a desktop computer. It can also be a laptop or other portable computer connected to the telephone network over a wireless connection.

The computer's connection can be shared by other telephony equipment. For an application to operate properly in this arrangement, neither the application nor the service provider can assume that there are no other active devices on the line.


The Telephony Model

The service provider must implement and export the Telephony Service Provider Interface (TSPI) functions needed to ensure that the requests from the TAPI dynamic-link library (DLL) are carried out correctly.

The service provider must process all requests received from the TAPI. A service provider does not have access to other service providers.

Although TAPI grants simultaneous access by multiple applications to a single service provider, the service provider is not responsible for managing this access.

TAPI assigns a device identifier to each service provider. The set of device identifiers for all services providers is contiguous and nonoverlapping.

The service provider supports the low-level, device-specific aspects of telephony. This includes functions that manage the states of calls, dialing, signal generation and detection, and switchboard controlling.

The implementations of such functions differ greatly from one device to another. For example, a service provider that provides direct management of analog phone lines can contain and control hardware for detecting onhook/offhook signals, generating and filtering tones, and so on. A service provider that worked in conjunction with a PBX can send command streams over a digital network to request similar operations from a piece of remote hardware. Service providers hide the device-specific details of how telephony operations are implemented.


Device Classes

There are two device classes: line and phone. Each device has a corresponding set of TSPI functions and messages. A line device is any device that has line behavior. A phone is any device that has phone behavior. The service provider implements this behavior by mapping requests into actual device commands.

The SPI can be mapped to a wide range of environments, including those not traditionally thought of as telephony environments. Phone devices and calls on line devices are capable of carrying media streams, such as voice, data, and video.


Line Device

Each line has one or more channels. The channels are identical and therefore interchangeable. The service provider can pool channels for use as shared resources. The service provider can also combine two or more channels for use in a single call to provide a wider bandwidth for exchange of information. This technique is often called inverse multiplexing.

The service provider allocates one or more channels in a line in response to a request to make or answer a call. Because a line's resources have identical capabilities and are interchangeable, there is no need for TAPI to explicitly identify the channels to be used. The service provider owns and completely manages the channels of each line.


Phone Device

Service providers are not required to support phone devices. Line and phone devices are independent devices. Service providers that fully implement this independence can offer uses of the line and phone devices to the applications that are not defined by normal telephony protocols. For example, you can use the handset of the desktop's phone as a wave form audio device for voice recording or playback, and, depending on the implementation, you may be able to do it without the switch knowing that the phone is in use. In such an implementation, lifting the local phone handset may not automatically send an offhook signal to the switch. This feature also allows your application to ring the local phone, independently of incoming calls. Capabilities of actual service providers may be limited by the hardware and software used to interconnect the switch, the phone, and the computer. TSPI includes functions to retrieve device capabilities that allow clients to determine whether such a usage model is supported.


Call Objects

Call objects are dynamically created and have no external names. A call object represents the local endpoint of a connection to one or more remote parties. A call object can come into existence on demand (for outbound calls) or spontaneously (for inbound calls). Calls are strongly tied to the line on which they occur; functions to create calls take a line object as a parameter to indicate their parent line. Call objects are used as parameters to the functions that operate on calls, including the operation to end the lifetime of a call. Calls remain subordinate to lines in several senses, for example, closing a line forces the calls on that line to be destroyed.


Service Levels

The Telephony Service Provider Interface defines three levels of service:

  • Basic Telephony The lowest level of service, which provides a guaranteed set of functions that are equivalent to POTS functions (make and receive calls). All service providers must support Basic Telephony functions.
  • Supplementary Telephony Provides advanced switch features such as hold, transfer, and so on. All Supplementary services are optional; that is, the service provider is not required to support them.
  • Extended Telephony Provides well-defined API extension mechanisms that enable application developers to access service-provider specific functions not directly defined by the Telephony API.

The set of TAPI functions do not map one to one onto the set of TSPI functions. In particular, functions related to privilege, phone number translation, and interapplication communication are handled by TAPI and have no corresponding function in TSPI. Other functions, such as those used for service-provider configuration and initialization, have no corresponding functions in TAPI.


Basic Telephony Services

The lowest level of service is called Basic Telephony, which provides a guaranteed set of functions that are equivalent to POTS functions (make and receive calls). All service providers must support Basic Telephony functions.

Note Phone-device services are optional. Phone device services are not a part of Basic Telephony.


Supplementary Telephony Services

Supplementary Telephony includes features found on modern PBXs, such as hold, transfer, conference, park, and so on. All supplementary features are optional.

A service provider offers any combination of the services. A service provider specifies which services it supports through responses to functions such as TSPI_lineGetDevCaps or TSPI_lineGetAddressCaps. A single supplementary service can consist of multiple function calls and messages.

Note TAPI, and not the service provider developer, defines the behavior of each of these supplementary features.

A service provider should provide a supplementary telephony service only if it can implement the exact meaning as defined by TAPI. If not, the feature should be provided as an Extended Telephony service.

All phone-device services are part of Supplementary Telephony.


Extended Telephony Services

A service provider can extend TAPI using device-specific extensions. The service provider must uniquely identify the extensions by using an extension identifier. Applications retrieve and use this unique identifier to determine what extensions the service provider supports.

The extensions can apply to several manufacturers. Special functions and messages such as lineDevSpecific and phoneDevSpecific are provided in TAPI. They are used to allow the extension of the set of functions (in contrast to enumerations, bit flags, and data structure members) supported by the service provider. The parameters for each function are also defined by the service provider.

An identifier is assigned to a set of extensions (before distribution), not to each individual instance of an implementation of those extensions. The EXTIDGEN utility in TSPI generates unique extension identifiers for service providers. It uses an Ethernet-adapter address, a random number, and the time of day to generate an identifier, so it is extremely unlikely that the resulting extension identifier will conflict with any other service provider. As a result, there is no need for vendors to register extension identifiers.

The EXTIDGEN utility does not generate extension identifiers unless the computer on which it is run is also running NetBIOS or other network software.


Addresses

An address is the telephone number, complete with national or international codes, of a telephone, fax machine, or other device that can receive calls. Addresses can be dialed by a human or stored in an electronic directory for retrieval and use (dialing) by a telephony application.

A line can have a local address. The user or an application sets this address when installing the service provider that supports the line. The service provider controls the local addresses of a line. In the simplest case, each line has one address. However, any line can have more than one address.

The service provider has a configuration. The service provider gives users access to the configuration settings by providing a TSPI_lineConfigDialog function.

In POTS, multiple addresses work only with systems that support distinctive ringing or are connected to a DID (direct inward dialing) trunk. DID is an extra-fee service provided by the phone company. With DID in a multiuser voice mail system, the dialed number is signaled to the system on the DID trunk before the call rings. This allows the system to play the called party's pre-stored announcement message and to store any incoming messages in the correct voice mailbox.

On a residential line with distinctive ringing service, different ringing patterns correspond to multiple numbers assigned to the same line.

ISDN allows simultaneous multiple addresses by providing multiple channels, each having a unique address.


Call Control

TAPI uses a first-party call control model on the logically terminated line, as well as control of the associated phone device, if any. Service providers must allow applications to control telephone calls as though they were an endpoint (the initiator or the recipient) of the call.

The application can make calls; be notified about inbound calls; answer inbound calls; invoke switch features such as hold, transfer, conference, pickup, and park; and can detect and generate DTMF (Dual Tone Multi-Frequency) tones for signaling remote equipment. An application can also use TAPI functions to monitor call-related activities occurring in the system.

In contrast, third-party call control means that the controlling application does not act as an endpoint of the call. A third-party call control model allows an application to establish or answer a call between any two parties; the application does not act as either of these parties.

A service provider can treat a set of stations on the switch as a single line device to which multiple phone numbers are assigned. Each phone number on the line device maps to one of the stations on the switch. The application can answer calls or make calls, selecting any one of the addresses on the line device as the origination number. Although the application appears to be the originating party, a call is actually established between the station whose address was selected by its originating number and the other party. However, this implementation is a type of third-party call control and is not a design goal of TAPI, which emphasizes first-party call control applications.

Each individual station on the switch is identified by its primary phone number (or other means). A possible implementation of the line and phone behavior by a service provider is to model the collection of all stations on the switch as a single line device that has multiple phone numbers assigned to it; each phone number on the line device, in reality, maps to one of the stations on the switch.

TAPI can make and answer calls, selecting any one of the addresses on the line device as the origination number.

Although TAPI appears to be the originating party, in reality, a call will be established between the station whose address was selected by its originating number and the other party.

A distributed service provider supports calls shared by multiple computers in a local area network by communicating with service providers on the other computers.


Media Access

The media mode is the form in which data is transmitted on a line. The four main types of media mode are voice, speech, fax, and data. The media stream is the actual stream of information that travels on the line. Calls can be established independently of the media mode.

The TSPI line and phone device classes only provide control operations for these devices. Access to media streams is not provided by the Win32 Telephony SPI. Applications must use other Win32 APIs, to provide this access or otherwise manage these media streams, such as the waveform API or the higher-level MCI interface.

A TSPI function identifies the appropriate media device, such as a wave device, to open and use to generate and access the media stream. The service provider determines the relationship between the phone or line device and the media device. The service provider must provide the TSPI function that specifies the relationship between the phone or line device and the media device. The physical device supports line, phone, call and wave device classes.

For line devices, the service provider receives a request to establish a connection to another station. After a call is established, the service provider receives a request for the media device associated with the call device. After information has been transmitted or received on the media device, the service provider receives a request to shut down the call.

Each telephony device class has a corresponding media device class. The service provider reports media stream type changes when requested. This process is sometimes referred to as call classification. The mechanism used to determine the type of a media stream (such as voice, fax, data modem) is service-provider specific.

A service provider can filter the media stream for energy or tones that characterize the media type. Alternatively, the service provider can determine the type by messages exchanged over the network, by use of distinctive ringing, or by knowledge about the caller or called ID.


Control of Media Stream

Some TSPI functions provide limited support for control of a media stream. A service provider typically implements these functions to prevent data loss in configurations in which the information of a call is passed between client and server computers.

If a service provider supports media control, it must accept requests to carry out actions on the media stream when given events occur, such as on receiving a specific tone or DTMF digit in the media stream. For example, the service provider might receive a request to suspend the media stream when it detects a # DTMF digit, and resume the media stream when it detects a * DTMF digit.

Media control is optional.


Initialization

The TSPI_providerInit and TSPI_providerShutdown functions are for initialization and shutdown.

Because TSPI defines initialization and shutdown functions, the service provider does not need to provide an initialization routine or WEP function as used in other dynamic-link libraries. The initialization and shutdown functions can be called multiple times while the service provider is active (in memory).

Because the service configuration can change while a service provider is active (in memory), the service provider must reinitialize all configuration-related information whenever the TSPI_providerInit function is called. All stored information from previous invocations may have become invalid.


Entry Points

TAPI links to and calls the TSPI functions using the standard dynamic-link library functions.


Callback Functions

The service provider reports events by calling TAPI-supplied callback functions.


Structures in TSPI

A service provider uses structures to receive and return the data associated with a telephony request. In many cases, the members in a structure vary in length or number depending on the context of the specific request.

The structures do not contain pointers.

DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;
       // fixed size fields
    DWORD  dwField1Size;
    DWORD  dwField1Offset;
       // fixed size fields
    DWORD  dwField2Size;
    DWORD  dwField2Offset;
       // common extensions
       // var sized field1
       // var sized field2

A structure consists of a fixed set of members, followed by zero or more variable members.

The first three fixed members specify the size of the structure. The dwTotalSize member, set by the application and verified by TAPI, specifies the total size in bytes of memory allocated for the structure. The dwNeededSize member specifies the total size in bytes needed for the data to be filled into the structure. The dwUsedSize member indicates the total size in bytes of the data that is actually filled in.

Each variable member has a pair of corresponding fixed members that specify the size and the offset, in bytes, from the beginning of the structure to the variable member.

Before passing a structure to the service provider, TAPI ensures that the memory for the structure is writable and that the value in dwTotalSize covers at least the fixed part of the structure. TAPI sets the dwUsedSize and the dwNeededSize members to the size of the fixed part.

If the service provider is responsible for filling in a variable member, TAPI sets the corresponding size and offset members to zero. If the service provider fills in the variable member, it must set the corresponding size and offset members to appropriate values. The service provider must not truncate a variable member to make it fit into the available space.

The service provider must:

  • Set the fixed and variable members for which it is responsible.
  • Update the dwUsedSize member if it sets variable members. This must be the size of all fixed members, plus the size of all variable members the service provider was able to copy to the available space.
  • Update the dwNeededSize member if it has any variable members. This must be the size of all fixed members plus the size of all variable members, not just those copied to the available space.

The service provider must start variable members immediately after the fixed members of the structure, and leave any extra space at the end of the allocated memory so that TAPI can use it for the variable-length members for which it is responsible. It can place the variable members in any order, but the members must be contiguous.

If the service provider detects an error, it must return the appropriate error return; no members need to be filled in. Insufficient space for variable members is not an error. The service provider simply sets dwUsedSize and dwNeededSize as appropriate and returns SUCCESS. Unless an error occurs, the service provider must set all fixed members for which it is responsible.

TAPI sets the fixed and variable members that it is responsible for after the service provider.


Protected-Mode Operation

Service providers are intended to be run in protected mode. Therefore, the PROTMODE flag must be given in the service provider module definition file (.DEF) to ensure proper operation.


Life Cycle

A session is the time during which a particular configuration remains valid and telephony operations are carried out. A service provider can support many sessions between the time it is first loaded and when it is finally freed. For each session, TAPI negotiates the version of the interface, starts the session, carries out operations, and eventually shuts down the session. The service provider must not retain information from one session to the next.

Version negotiation consists of TAPI sending the range of versions of the interface that it can support and the service provider responding with the version or versions in that range that it can support.

Because TAPI negotiates the version, you can upgrade a service provider to new versions of the interface without requiring that TAPI also be upgraded. Similarly, TAPI can be upgraded, yet still use your older service provider.

After the interface version is known, TAPI calls the TSPI_providerInit function to set all operational parameters. The service provider is ensured that all of the configuration information in the registry is stable when the TSPI_providerInit function is called. Most service providers read all configuration information at that time.

Normal operations can proceed in any order, after the service provider is initialized.

TAPI negotiates device-specific on a per-device basis. TAPI and the service provider commit to a version when a device is opened.

The service provider can receive requests to select and cancel extension versions. While an extension version is selected, the device operates strictly according to that device-specific extension version.

Negotiation of a device-specific extension version can happen multiple times, both before and after the phone is opened. TAPI passes a version range, and the service provider chooses and returns a value from this range. Normally, the service provider has device-specific extensions disabled.

This commits both TAPI and the service provider to operating at that extension version level until the selection is canceled. During the time that a device-specific extension is in effect, an attempt to negotiate an extension version level should allow only the version level that is currently in effect. After the device-specific extension is canceled, a different version can be negotiated and selected.

Phone operations within the Open/Close pair are shown in the following illustration. Some of these operations are synchronous, others are asynchronous. If an operation completes asynchronously, another operation can be requested before the first reports completion. Thus, operations can overlap in any way. The service provider must eventually report completion for any asynchronous operation requested. Closing the phone forces outstanding asynchronous operations to complete (possibly with a "failure" indication).

The life cycle for line devices is similar to the life cycle for phones, except that lines have their own negotiation, initialization, open, and close procedures. Operations on open lines are bracketed by their own Open/Close pair. This pair is in turn bracketed between the same Initialization/Shutdown pair as the phone Open/Close.

The life cycles of calls are bracketed strictly between the Open/Close of the line that contains them. Lifetimes of calls can begin in several ways:

  • Requested from TAPI through functions such as lineMakeCall, lineSetupTransfer, or lineSetupConference.
  • Spontaneously originated in the service provider as new incoming calls, user-initiated calls on an attached telephone handset, or calls generated as a side effect of other operations such as putting an existing call on hold.

The lifetimes of distinct calls within the same line can overlap each other in any way. All calls end their lifetime at the time the TSPI function TSPI_lineCloseCall is invoked. The life cycle of several calls is shown in the following illustration:

A call can originate in TAPI as shown with the MakeCall/CloseCall pair. A call can also originate in the service provider. The service provider announces this with a LINE_NEWCALL message to a TAPI-supplied callback procedure. In such a case, TAPI returns its identifier for the call, which is included in subsequent callbacks reporting events occurring on the call. In the case of calls whose lifetime originates in TAPI, this identifier is included in the TSPI operation that creates the call.

All of the operations that start the lifetime of a call result in TAPI and service provider exchanging identifiers for the new call. In the case of TAPI originated calls, TAPI passes its identifier and receives the service provider's identifier as a return parameter. In the case where the call originates in the service provider, the service provider passes its identifier to TAPI and receives the TAPI identifier as a return parameter.

The following illustration offers a very high-level view of service provider installation, configuration, and removal; life-cycle sequences that span many sessions. The typical life-cycle for these operations can be shown with the following time line:

The typical installation and removal life cycle is shown, spanning multiple sessions. Calls to the Install and Remove procedures are strictly paired and do not overlap. Calls to the Config procedure can happen multiple times within this pair. One is typically done by the service provider as an internal side effect of the Install procedure to create line and phone entries. The Config procedure may be called at other times to alter an existing setup. The Install procedure must be done before any other TSPI function is permitted. In the ideal scenario, all sessions are strictly nested within the Install/Remove procedure pair.

The functions TSPI_providerInstall , TSPI_providerConfig, and TSPI_providerRemove interact with the service provider itself rather than with any specific device. They affect static configuration information that survives across multiple sessions and must be present for any other operation to proceed. Thus, all other operations are nested between the invocation of TSPI_providerInstall and the completion of its matching TSPI_providerRemove. These two operations typically happen very far apart, most likely in a different load of the service provider or a different boot of the machine. Calling the Config function externally is optional, because the Install procedure is required to include the Config behavior in addition to its own. The usual reason for calling it externally is to modify an existing configuration.

There is a subtlety embedded in the concept of the completion of a TSPI_providerRemove operation. It is desirable to allow the user to run the Telephony Control Panel utility supplied with the telephony service to alter service provider configurations, even when telephony operations (sessions) are in progress. Consequently, both the TSPI_providerConfig and TSPI_providerRemove specifications allow for invocation while there is an outstanding session. However, any changes to the configuration are required to be delayed until telephony operations are shut down and restarted. Thus, strictly speaking, the completion of any TSPI_providerConfig or TSPI_providerRemove operation happens outside any session. The nesting of actions is as shown in the figure, even though the procedures calls may appear in a slightly different order. It is permitted for a service provider to simply disallow Config or Remove while operations are in progress, although the user should be notified with a dialog box. A more user-friendly implementation that allows at least a subset of operations is preferred.

These Install, Config, and Remove operations all have the side effect of signaling any running telephony applications, which eventually results in them shutting down their use of the telephony service. Together, this ends all outstanding sessions for service providers. This signifies to service providers that they must read the new registry configuration when new sessions begin. Any changes that were pending due to a Config or Remove while operations were in progress then take effect.


The Synchronous/Asynchronous Model

Telephony operations complete either synchronously or asynchronously. These two models differ as follows.

  • Asynchronous operations have a parameter named dwRequestID of the defined type DRV_REQUESTID as their first parameter. Such an operation performs part of its processing in the function call and the remainder of its processing in an independent execution thread after the function call has returned. When the function returns, it returns either a negative error result or the (positive) dwRequestID that was passed in the function call. The negative error result indicates that the operation is complete (and failed). The positive dwRequestID returned indicates that the operation continues in the independent thread. In such a case, the service provider eventually calls the ASYNC_COMPLETION procedure, passing the dwRequestID and a result code to indicate the outcome of the operation. The result code is zero for success or one of the same set of (negative) error results. In any case, the service provider must never return zero or any positive value other than dwRequestID from a function designated as asynchronous because doing so can produce unexpected results. Service providers should always copy input data from application memory into service provider memory before returning from an asynchronous function.
  • Synchronous operations do not have dwRequestID as their first parameter. Such an operation performs all of its processing in the caller's execution thread, returning the final result when it returns. The result is zero for success or a negative error code for failure. The service provider does not call ASYNC_COMPLETION for synchronous operations.


The Meaning of SUCCESS

When an operation returns a SUCCESS indication (either synchronously upon function return for synchronous operations, or asynchronously with a call to the ASYNC_COMPLETION callback procedure for asynchronous operations), then the following are assumed to be true:

  • The function has successfully progressed up to a service-provider-defined point. The service provider defines the point on a function-by-function basis. After reaching that point, either the operation is completely finished, or it is in a state such that subsequent independent state messages will inform the application about progress.
  • Functions that return information (such as TSPI_linePark or TSPI_lineDevSpecific) return SUCCESS only when the requested information is available to the caller. Functions that return handles (to opened lines, opened phones, or calls) return the handles immediately on function return. The handles must be treated by both the service provider and the caller as "not yet valid" until the eventual SUCCESS indication. The service provider is responsible for preventing any callback messages to the LINEEVENT or PHONEEVENT procedure about that opened line, opened phone, or call until after the SUCCESS indication. If the eventual result is an error, any handle returned immediately becomes invalid without any further action.
  • Functions that enable certain permanent conditions (like TSPI_lineMonitorDigits) return SUCCESS only after the condition is enabled, not when the condition is removed again (for example, not when digit monitoring is complete).
  • Call control functions (such as TSPI_lineHold and TSPI_lineSetupTransfer, but not TSPI_lineMakeCall) return SUCCESS when the operation is completed. In telephony environments that do not provide positive acknowledgment of these functions, the service provider is forced to make a best-effort decision as to the success or failure of the function.
  • A service provider's implementation of TSPI_lineMakeCall must return SUCCESS no later than when the call enters the proceeding call state. Ideally, the provider indicates SUCCESS as soon as possible, such as when the call enters the dialtone call state (if applicable). When SUCCESS is returned to the application, LINE_CALLSTATE messages inform the caller about the progress of the call. Service providers that delay returning the TSPI_lineMakeCall SUCCESS indication, for example, until after dialing is complete, severely limit flexibility at the application level. Delay in returning SUCCESS in TSPI_lineMakeCall prevents a user from canceling the call setup request in progress until after dialing is complete, and all digits are sent to the switch.


Synchronous versus Asynchronous Requests

Some TSPI functions operate synchronously, while others operate asynchronously. Synchronous functions execute the entire request before the caller's thread is allowed to return from the function call. Asynchronous functions return from the function call before the request has executed in its entirety. When the asynchronous request later completes, the service provider reports the completion by calling a callback procedure originally supplied to it by tapi32.dll early in the initialization sequence.

To support asynchronous functions, tapi32.dll passes an asynchronous request identifier to the service provider as part of the function call. Request identifiers are positive integers strictly greater than zero. The service provider does whatever is required to start the operation and then returns the request identifier to tapi32.dll. When the asychronous operation eventually completes, the service provider reports completion by calling a special callback procedure (ASYNC_COMPLETION) in tapi32.dll. The parameters to this procedure are the original request identifier and the result code. Result values are 0 for success and negative values for error indications.

For synchronous functions, the service provider simply runs the entire operation to completion. If the operation succeeds, it returns zero. If an error occurs, it returns a negative error number. TAPI does not pass a request identifier to synchronous functions.

It is interesting to consider the timing of a "completion" callback relative to when the original request returns. A typical asynchronous request would be implemented by the service provider as in the following pseudocode:

Some_request(Request_ID, ...) {
  check parameters for validity
  check device state for validity
  store Request_ID for Completion Interrupt Handler's use
  manipulate device registers to start physical operation
  return Request_ID  // to indicate asynch operation
}
Operation Completion Interrupt Handler: {
  if operation was successful then
    call "completion" callback passing Request_ID and "success"
  else
    call "completion" callback passing Request_ID and "error num"
  endif
}

If the operation completes very rapidly (or the original request returns very slowly), it is possible that the Interrupt Handler that runs when a physical operation completes may be triggered before the original request returns to the application or even tapi32.dll. This behavior is allowed. The tapi32.dll guarantees that the eventual completion notification to the application is delivered after the original request returns.


Synchronous Requests

Service provider designers should try to keep the execution time of synchronous operations short. For example, there is an "Open" operation called at initialization time that prepares the service provider and TAPI for subsequent operations on a device. A service provider whose implementation is split between the client computer and a dedicated server may have reasonable confidence that it can communicate with its remote server. Its implementation of "Open" might just allocate and initialize data structures to represent the device and return, postponing end-to-end communication until some real operation is requested.

Any such "optimistic" implementation of a synchronous operation can later encounter resource limitations or remote communication failures. In general, these cannot be entirely prevented even by a "conservative" approach; service-provider designers must choose the best tradeoff between reliability and performance. A failure of this kind should be handled gracefully wherever possible. From the point of view of TSPI devices should remain valid for "bookkeeping" purposes even if they return failure status for any operation requested.

Implementing an optimistic approach for synchronous requests should not be done at the expense of correct semantics for the operation. Returning to the "Open" example, if opening a device needs to compete for and reserve a scarce, nonsharable resources such as communication ports, it should probably do so even if it is time-consuming.


Asynchronous Spontaneous Events

There is another class of asynchronous events besides those described above. These events are "spontaneous" in the sense that they are not direct results of corresponding requests. These events are detected in such cases as when an incoming call arrives, or when an outbound call goes from a "ringing" to an "answering" state. When tapi32.dll first initializes interactions with the TSPI for a particular device, it passes a pointer to a callback procedure to be called for reporting such spontaneous events. Along with this procedure pointer is a device handle that the service provider includes as one of the actual parameters to the callback.


Call-less Asynchronous Operations

There are five asynchronous operations which are not related to any particular call. These are initiated by the TAPI lineDevSpecific, lineDevSpecificFeature, lineForward, lineSetTerminal, and lineUncompleteCall functions. If an application initiates one of these asynchronous operations and calls lineClose, the service provider may receive no indication that the application has abandoned the function. This can occur if the application was not the only application to have the line open. If the application calls lineClose with one of these operations pending, and it is the only application with a handle to the line, TAPI calls the TSPI_lineClose function and the service provider should terminate the asynchronous operation, calling the ASYNC_COMPLETION callback function for each such outstanding operation with the LINEERR_OPERATIONFAILED error value.


Termination of Asynchronous Operations

When an application calls the lineClose function with one or more outstanding asynchronous operations, TAPI may direct the service provider to terminate asynchronous operations assocated with a call, depending on whether the application is the sole owner of the call and has the only handle to the call.

If the application is the sole owner of a call, TAPI calls TSPI_lineDropOnClose or TSPI_lineDrop (depending on the provider) for each such call. The service provider should check for any pending asynchronous operations associated with the call being dropped. If a pending operation exists, the service provider should take the appropriate action, possibly terminating the operation in progress.

If the application has the only handle to a call (that is, there are no other owners or monitors), TAPI calls the TSPI_lineCloseCall function. The service provider must consider this call to be the absolute indication that pending asynchronous operations must be abandoned. The service provider must ensure an orderly completion of the call, and must call the ASYNC_COMPLETION callback function for all outstanding asynchronous operations, specifying the LINEERR_OPERATIONFAILED error value. If TAPI previously called the TSPI_lineDropOnClose or TSPI_lineDrop function, it calls TSPI_lineCloseCall immediately after the service provider returns from the other call; it does not wait for the asynchronous operation associated with the TSPI_lineDrop function to complete.

If the application is not the sole owner of the call, TAPI does not call TSPI_lineDropOnClose or TSPI_lineDrop. If the application does not have the only handle to the call, TAPI does not call the TSPI_lineCloseCall function. If the application is neither the sole owner nor the sole possessor of a handle to the call, TAPI sends no notification to the service provider, and therefore, any pending asynchronous operations remain intact. This means that such applications cannot terminate asynchronous operations that they have started by using the lineClose function. However, because every asynchronous operation requires the invoking application to be an owner of the call, the likelihood of an application not being able to terminate asynchronous operations is very rare. If it does occur, the other owner(s) of the call(s) must take responsibility for the disposition of the call(s).

If TAPI calls TSPI_lineDropOnClose or TSPI_lineDrop, the service provider must eventually send a LINECALLSTATE_IDLE message for the associated call (unless TSPI_lineCloseCall is called first) so that monitors on the call can clean up. When the last monitor has called the lineDeallocateCall function, TAPI calls the TSPI_lineCloseCall function; any pending operations must be completed or terminated and ASYNC_COMPLETION called, as described earlier.


Call States and Events

A connection is not fully established until both parties are communicating. To reach that point, the establishment of the call goes through several stages, as does the clearing (termination) of the call. A call's events cause it to transition through call states as it comes into existence, is used to exchange information, and terminates. This topic lists and describes the various call states.

Call-state transitions result from both solicited and unsolicited events. A solicited event is one caused by the application controlling the call (as when it invokes TAPI operations), while unsolicited events are caused by the switch, the telephone network, or the actions of the remote party. Some operations on line devices, addresses, and calls may first require that the line, address, or call upon which they operate be in certain specific states.

Different call states indicate that connections exist to different parts of the switch. For example, a dial tone is a particular state of a switch that means the switch is ready to receive digits.

Whenever a call changes state, the service provider reports the new state in a callback to tapi32.dll. Due to the asynchronous way in which these reports arrive and are forwarded to the tapi32.dll client applications, the programming model the application developer should follow is not one that presumes a rigid call state machine, but one where the application can react to the events reported to the application. In other words, call-state notification tells the application what the call's new state is instead of reporting the transitions between two states.

Some of the call states and events defined by TAPI are exclusive to incoming or outgoing call processing, while others occur in both cases. Several of these call states provide additional information that can be used by the application. For example, the busy state signifies that a call cannot be completed because a resource between the originator and the destination is unavailable, as when an intermediate switch has reached its capacity and cannot handle an additional call. Information supplied with the busy state includes station busy or trunk busy. Station busy means that the destination's station is busy (the phone is offhook), while trunk busy means that a circuit in the switch or network is busy. The call states defined in Win32 Telephony are listed below:

Call State | Description
idle | This corresponds to the null state: No activity exists on the call, which means that no call is currently active. This state occurs at the end of a call, but never at the beginning of a new call. If a service provider changes the call state to idle, it must not subsequently change the call to any other state. The idle state should be the last state a call enters and it should remain in that state until TSPI_lineCloseCall is called to dispose of it.
offering (incoming) | When the switch informs the computer of the arrival of a new incoming call, that call is in the offering state. The offering state is not the same as causing a phone or computer to ring. When a call is offered, the computer is not necessarily instructed to alert the user.
 | For example, an incoming call on a shared call appearance is offered to all stations that share the appearance, but typically only the station that has the appearance as its primary address is instructed to ring. If that station does not answer after some amount of time, the bridging stations may be instructed to ring as well.
accepted (incoming) | An application has taken responsibility for an incoming call. In ISDN, the accepted state is entered when the called-party equipment sends a message to the switch indicating that it is willing to present the call to the called person; this has the side effect of alerting the users at both sides of the call: the caller's and the called party's. An incoming call can always be immediately answered without first being separately accepted.
dial tone (outgoing) | Indicates that the switch is ready to receive a dialable number. In most telephony environments, this state is entered when an audible dial tone is detected by the line device. Additional information includes:
—normal dial tone | The "normal" or everyday dial tone, usually a continuous tone.
—special dial tone | A special dial tone is often used to signal certain conditions such as message-waiting. This is usually an interrupted dial tone.
dialing (outgoing) | The originator is dialing digits on the call. The dialed digits are collected by the switch.
proceeding (outgoing) | The call is proceeding through the network. This occurs after dialing is complete and before the call reaches the dialed party, as indicated by ringback, busy, or answer.
special info (outgoing) | The call is receiving a special information signal. A special information signal precedes a prerecorded announcement indicating why a call cannot be completed. Such announcements can be of these types:
—no circuit | A no-circuit or emergency announcement.
—customer irregularity | An announcement meaning that the dialed number is not correct.
—reorder | A reorder or equipment-irregularity announcement.
busy (outgoing) | The call is receiving a busy signal. Busy indicates that some resource is not available and the call cannot be normally completed at this time. Additional information consists of:
—station busy | The station at the other end is offhook.
—trunk busy | The network is congested. This usually produces a fast busy signal.
ringback (outgoing) | The station to be called has been reached, and the destination's switch is generating a ring tone back to the originator. A ringback means that the destination address is being alerted to the call.
connected (incoming and outgoing) | Information is being exchanged over the call.
onHold (incoming and outgoing) | The call is currently held by the switch. This frees the physical line, which allows another call to use the line.
conferenced (incoming and outgoing) | The call is a member of a conference call and is logically in the connected state (to the conference bridge). Every call in the conferenced state is linked to the parent conference call, which will be in a state such as connected, onHold, and so forth).
on hold pending conference (incoming and outgoing) | The conference call is currently on hold and waiting for the user to add another party.
on hold pending transfer (incoming and outgoing) | The call is on hold in preparation of being transferred.
disconnected (incoming and outgoing) | The call has been disconnected by the remote party.
unknown (incoming and outgoing) | The call exists, but its state is currently unknown. This may be the result of poor call progress detection by the service provider. A call state message with the call state set to unknown may also be generated to inform TAPI about a new call at a time that the actual call state of the call is not exactly known.

Although under normal circumstances an outgoing call is likely to transition to connected through a number of intermediate states (such as dial tone, dialing, proceeding, and ringback), other paths are possible as well. For example, the ringback state may be skipped, as when a "hot phone" (or other nondialed phone) transitions directly to connected.

An application should always process call-state event notifications. Call-state transitions valid for one switch or configuration may be invalid for another. For example, consider a line from the switch that (using a simple Y-connector) physically terminates both at the computer and at a separate phone set, creating a party line configuration between the computer and the phone set. The computer termination and, therefore, the application using TAPI, may not know of the activities on the line handled by the phone set. That is, the line may be in use without the service provider being aware of it. An application that wants to make an outgoing call will succeed in allocating a call appearance from the API, but ends up sharing the active call on the line. In this case, blindly sending a DTMF dial string without first checking for a dial tone may not result in intended (or polite) behavior.


Call State Functions and Messages

The LINE_CALLSTATE message is sent to an application to notify it about changes in a call's state. The TSPI_lineGetCallInfo function returns mostly constant information about a call as a data structure of type LINECALLINFO. The TSPI_lineGetCallStatus function returns complete call status information for the specified call as a data structure of type LINECALLSTATUS.

The call information data structure maintained for each call contains an application-specific field that applications can read from and write to. This field is not interpreted by the service provider. Applications can use it to tag calls in application-specific ways. Writing to this field so that the change is visible to other applications requires that the application use TSPI_lineSetAppSpecific, which sets the application-specific field of a call's information structure.


Line Devices

A line device is a physical channel composed of a telephone line and the hardware that controls it, such as a fax board, a modem, or an ISDN card. The simplest kind of line device corresponds to exactly one telephone line. In general, telephony allows a line to contain a pool of multiple homogeneous channels that can be used to establish calls. A service provider that implements a line as a pool of channels allocates those channels out of a set of physical lines it controls, or multiplexes multiple channels onto a single physical line. Although the term line often connotes something with two endpoints, within TAPI the term refers just to one endpoint of a communication channel or point of entry into a telephone switching network.

Depending on the environment, a service provider can restrict calls to one per line as in POTS, allow switching between several calls on a single line while others go on hold, or allow multiple calls to be active concurrently.

The following illustration displays the variety of hardware (driven by the same TSPI functions) that can exist within one configuration.

Although the four lines in the preceding illustration employ different hardware and are used for different functions, their respective service providers abstract them to the same device type, and they are controlled through the same TSPI functions. In the case of the voice-oriented Line 4, its service provider may allow the line to be directly connected to a telephone handset for incoming or outgoing calls. The service provider may also allow software access to the phone by making it available as an instance of the phone-device class, which is described in Device Classes.

TAPI requires that every TAPI-capable line device support all of Basic Telephony. If an application needs to use capabilities beyond those of Basic Telephony (namely Supplementary or Extended Telephony), it must first determine the line device's capabilities, which can vary according to network configuration (client versus client/server), hardware, service-provider software, and the telephone network.

The TSPI_lineGetDevCaps function queries a specified line device to determine its telephony capabilities. The returned information is valid for all addresses on the line device. The dwExtVersion parameter of TSPI_lineGetDevCaps indicates the version number of the extension information requested. If it is zero, no extension information is requested. If it is nonzero, it holds a value that was already negotiated for this device with the TSPI_lineNegotiateExtVersion function. The service provider should fill in device- and vendor-specific extended information according to the extension version specified.

Note The service provider should also fill in all the members of the LINDEVCAPS data structure, except for dwTotalSize, which is filled in by tapi32.dll. The service provider must not overwrite the dwTotalSize member.


Relationships Between Lines, Channels, and Addresses

In POTS, exactly one channel exists on a line, and this is used exclusively for voice. With ISDN, at least three (and as many as 31) channels can exist on a line concurrently. The simplest form of Win32 Telephony functionality involves POTS applications that handle a single line using its single channel. In POTS, an application that wants to transmit data communicates over one line, and a voice application communicates over another line; both of these applications could use the same line, but not at the same time.

In the simplest case, one line has exactly one address (telephone number). In cases where lines carry two or more channels, each channel usually has its own address, which means that a line has as many addresses as it has channels. To make addresses easier to manipulate, TAPI assigns address identifiers to them, in a contiguous range of integers starting with 0. This lets the software interfaces refer to addresses independently of the address syntax on any particular telephone network.


Multiple Addresses on a Single Channel

Some installations support the assignment of more than one address to a single channel. On POTS lines, multiple addresses are made possible by various systems, such as distinctive ringing or DID (direct inward dialing), which are extra-fee services provided by the telephone company.

Many large corporations use DID for incoming calls. Before a call is connected, its destination extension number is signaled to the PBX, which causes the extension to ring instead of the operator's phone. An example of distinctive ringing in a private home would be if the parents used one address, the children another, and a fax machine a third. Because only one line connects the house to the telephone network, all phones ring when a call appears, but the ring pattern is different depending on the number dialed by the calling party. With distinctive ringing, the people know who the incoming call is meant for, and the fax machine answers its calls by recognizing its own ringing style.

In ISDN, the various B channels do not normally have separate addresses, but are usually on the same address. For this reason, it is the switch (and not the application or a person who has dialed the number) that assigns calls to these channels.


ISDN Subaddresses

Subaddressing is a capability provided on ISDN lines that allows more information than just a single telephone number to be used when dialing. This additional information can specify an individual telephone extension to ring or, in a computing environment, can alert a particular application. Other parameters that can be passed can describe the required aspects of a requested modem connection, such as rate and timing.


Address Configurations, Functions, and Messages

Each line device is assigned one or more addresses. An address corresponds to a telephone directory number, and it is actually assigned twice: first, by the telephone company at the switch, and second, by the user while configuring the local system. If a telephone number is changed at the switch, the user will normally need to assign the new number at the local system, although some systems may be sophisticated enough to perform the reassignment without human interaction.

After addresses have been assigned to lines, the service provider assigns address identifiers to addresses. An address identifier is a number between 0 and the number of addresses on the line minus one. Because each address depends on its line for its existence, the address's identifier is meaningful only in the context of the associated line device. For this reason, an address name consists of not only the address identifier, but also an identifier of the line.

More than one address can be assigned to a line device. (The number of assigned addresses is returned by the TSPI_lineGetDevCaps function.) These address-to-line assignments (as modeled by the Telephony SPI) are static in that they change only when reconfigured in any of several ways at the switch or network. The relationship between an address and a line and between the address and other local addresses is known as the address's configuration.

Usually, one of the addresses assigned to a line is that line's primary address. A primary address is the one address on a line that can uniquely identify the line device. This primary address may also be assigned to other lines as a nonprimary address.

The network or switch can configure address-to-line assignments in several ways. Usually, one of the addresses assigned to a line is that line's primary address. A line's primary address is able to uniquely identify the line device, although the address may also be assigned to other lines as a nonprimary address. Address configurations recognized by the Telephony SPI include:

  1. Private The address is assigned to one line device only. An inbound call for this address is only offered at one line device.
  2. Bridged A bridged address is a single address assigned to more than one line device. Depending on the switch vendor, different terminology may be used such as multiple appearance directory number (MADN), bridged appearance, or shared appearance. An incoming call on a bridged address is offered on all lines associated with the address. The network of lines connected together is known as the bridge. Different variations of bridged behavior are possible:
    • Bridged-Exclusive. Connecting one of the bridged lines to a remote party causes the address to appear in use to all other parties that are part of the bridge.
    • Bridged-New. Connecting one of the bridged lines to a remote party does not preclude the other lines from using the bridged address to answer or make calls. However, a new call appearance is allocated to another of the connected lines.
    • Bridged-Shared. If one line is connected to a remote party, other bridged lines that use the address automatically enter into a multiparty conference call on the existing call.
  3. Monitored The line indicates the busy or idle status of the address, but the line cannot use the address for answering or making calls.


Address-Related Functions and Messages

As is the case with line devices, the addresses assigned to a line device can have different capabilities. Switching features and capabilities (including authorization) can be different for different addresses. When an application calls lineGetAddressCaps, tapi32.dll calls TSPI_lineGetAddressCaps to determine the telephony capabilities of each address. The service provider must return the telephony capabilities of an address as a data structure of type LINEADDRESSCAPS. In a similar way, the service provider implements TSPI_lineGetDevCaps to provide an application with the number of addresses assigned to the line, as well as other information.

The TSPI device query capability, and status and event reporting mechanisms provide tapi32.dll with the information required to manage the different bridged address arrangements. For example, tapi32.dll can determine if a call has been answered by a bridged station by tracking the status changes and call state event changes on the address (see Call States and Events).

An address on a line device is normally identified through its address identifier. When making calls, TSPI allows alternate address selections for the originating address, such as its address in dialable format or even service provider-specific naming mechanisms (for example, by using TSPI extensions based on switch-assigned station identifiers). The TSPI_lineGetAddressID function maps the alternate address format back to the address identifier used by other functions in TSPI.

The tapi32.dll is notified about changes in the status of an address in the LINE_ADDRESSSTATE callback message. tapi32.dll can control the address status items for which it wants to be notified with the TSPI_lineSetStatusMessages function. It can determine the complete status of an address device by calling TSPI_lineGetAddressStatus.


Memory Allocation

Several TSPI functions return large amounts of information. Applications are responsible for allocating memory for this information; the service provider simply fills in the data. Some of these data structure members are filled in by tapi32.dll, and others are filled in by the service provider. The function descriptions in this section explain the division of responsibility between tapi32.dll and the service provider. The service provider must preserve the values in fields for which tapi32.dll is responsible. In any case, the service provider must fill in the fields it "owns" before reporting the operation complete. Note that, for functions that complete asynchronously, the filling of the data structure may be done synchronously or asynchronously, which in any case must be completed before the LINE_REPLY message is sent. When passed to the service provider from TAPI, the structure is filled with zeros, and then the TAPI fields are added, so it is not necessary for the service provider to explicitly write zero values to any field.


Call States

Most functions on calls only make sense while the call is in one of certain call states. This call state is checked, and the function returns an error if the call is not in one these states. The effect of the successful execution of a request may be some typical call state transitions. The service provider notifies TAPI about call state changes using call state messages. These messages report the state the call has just entered to TAPI and to applications. Because unsolicited events may occur to calls (as when the other party disconnects), tapi32.dll cannot assume that requests it issues always result in certain fixed call state transitions.

This model gives the service provider designer maximum flexibility across different telephony environments. For example, it allows designs in which requests propagate through a network to a Telelphony server, such as a PBX, while call state change reports propagate back to the local client at some later time. Such a design need not try to maintain a lock-step "view" of the current state of the call in both client and server that is always identical between the two sites.


Overall Comparison with TAPI

The TSPI specification is very closely related to the TAPI specification. Most of the functions in one interface have a corresponding function in the other interface. The usual correspondence is as follows:

  • TSPI functions have the same names as TAPI functions except that they are prepended with "TSPI_". For example, the TAPI function lineAccept corresponds to the TSPI function TSPI_lineAccept.
  • Procedures that allow asynchronous operation insert a dwRequestID parameter of type DRV_REQUESTID as their first parameter. This parameter specifies the value to be returned to indicate asynchronous operation and to report asynchronous completion.
  • hCall parameters of type HCALL are replaced with hdCall parameters of type HDRVCALL, indicating the service provider's handle for the call.
  • hLine parameters of type HLINE are replaced with hdLine parameters of type HDRVLINE, indicating the service provider's handle for the line.
  • hPhone parameters of type HPHONE are replaced with hdPhone parameters of type HDRVPHONE, indicating the service provider's handle for the phone.
  • Procedures that create a new call, such as TSPI_lineMakeCall, replace a single lphCall parameter with two parameters: an htCall of type HTAPICALL parameter that passes in the TAPI handle for the call, and an lphdCall of type LPHDRVCALL that indicates the location to which the service provider must write its new handle for the call. A similar split of parameters occurs in TSPI_lineOpen and TSPI_phoneOpen.
  • At the TSPI level, there is no notion of "privilege" associated with device handles. Furthermore, at the API level, each application that has a device or call handle has a different handle, but TAPI merges these into a single handle in the service provider side. As a consequence, the error codes and status messages relating to privilege and number of clients using a device do not appear at the TSPI level.


Error Checking

At the TAPI level, an application can pass a variety of different parameters, many of which may be invalid. tapi32.dll checks for bad parameters and returns errors to the application without calling the service provider. Each function description at the TSPI level describes the parameter errors that have already been tested. The service provider does not have to repeat these tests, though it must perform any additional validity tests appropriate to the function. Titles and descriptions of common parameter validity tests that appear in many functions are listed below.

Validity Test | Description
Pointer validity | tapi32.dll has already tested pointers to data storage to make sure that they point to readable or writeable memory of the size appropriate to the operation. In addition, for variably sized data structures starting with a dwTotalSize member, the data structure has been verified to ensure that the indicated total size is really available.
Fixed size validity | For variably sized data strucutres, the data structure has been checked to make sure that there is at least enough space for the fixed size part of the data structure and that dwTotalSize is sufficient to cover the fixed part.
Offset/size zeroed | For variably sized data structures, the "...Offset" and "...Size" fields corresponding to parts that the service provider fills in have been preset with zero values before the service provider was called.
Handle validity | tapi32.dll guarantees that line, phone, and call handles (of defined types HDRVLINE, HDRVPHONE, and HDRVCALL) are valid. That is, they are values that have been returned without error as handles in TSPI_lineOpen, TSPI_phoneOpen, or one of the following that starts the lifetime of a call handle: TSPI_lineMakeCall TSPI_lineCompleteTransfer TSPI_lineForward TSPI_linePickup TSPI_linePrepareAddToConference TSPI_lineSetupConference TSPI_lineSetupTransfer TSPI_lineUnpark LINE_NEWCALL messages


Basic Line Services

Basic line services offer POTS-level telephony features. This section discusses elements that are important in setting up a service provider that yields basic line services.


Line Initialization

As part of the line device abstraction defined by TSPI, tapi32.dll and the service provider must first perform some basic initialization. The first step is interface version negotiation. The tapi32.dll performs this by calling the TSPI_lineNegotiateTSPIVersion function. This function is usually used to negotiate on behalf of an individual line device; different line devices within the same service provider can operate under different interface versions. The tapi32.dll passes a special reserved device identifier value, INITIALIZE_NEGOTIATION, to indicate that it is negotiating an overall interface version for initialization functions that affect the entire service provider.

The result of this negotiation is passed to subsequent procedures until a line device is opened. At that time, the line device becomes committed to a particular interface version. This interface version is implicit until the line is closed, and does not need to be passed to subsequent functions that operate on an opened line or calls on the line.

Following overall interface version negotiation, tapi32.dll calls the TSPI_providerInit function. This function initializes the service provider, and gives it parameters required for subsequent operation. These parameters include the following:

  • dwPermanentProviderID Specifies the permanent identifier, unique within the service providers on this system, of the service provider being initialized.
  • dwLineDeviceIDBase Specifies the lowest device identifier for the line devices supported by this service provider. Devices of the telephony line device class are identified by integers starting at zero. This range of identifiers is contiguous across the full range of line devices. Because there can be multiple service providers managing line devices in a single system, each service provider obtains a contiguous portion of the total range. This parameter tells the service provider the lowest value in its portion of the range. The service provider, rather than tapi32.dll, is responsible for mapping this variable range to its own internal device identifiers. This gives the service-provider vendor sufficient flexibility to use device identifiers in device-specific extensions if it wants. Because the service provider knows what device identifiers appear in the TAPI-defined parameters and data structures, it can use consistent device identifiers in device-specific extension parameters and data structures.
  • dwPhoneDeviceIDBase Specifies the lowest device identifier for the phone devices supported by this service provider.
  • dwNumLines Specifies the number of line devices that this service provider supports.
  • dwNumPhones Specifies the number of phone devices that this service provider supports.
  • lpfnCompletionProc Specifies the procedure the service provider calls to report completion of all asynchronously operating procedures on line and phone devices.

Following TSPI_providerInit, normal operations such as opening lines can be performed.


Line Configurations

A line device can represent a pool of homogeneous resources (channels) that are used to establish calls. In a client computer, the Telephony SPI typically provides access to one or more line devices.

All line devices support at least the Basic Telephony services. If the tapi32.dll client application is interested in using Supplementary and/or Extended Telephony services, the application must first determine the exact capabilities of the line device. Telephony capabilities vary with configuration (such as client versus client/server), hardware, service-provider software, and the telephone network. Applications should not assume what telephony capabilities are available beyond Basic Telephony services. The tapi32.dll determines the line's device capabilities on behalf of an application using TSPI_lineGetDevCaps, which returns the supplementary and extended capabilities of a given line device as a data structure of type LINEDEVCAPS.

Here are some examples of how a service provider might model various configurations:

Example 1 A single POTS line in the computer-centric or phone-centric connection models. The most straightforward model is a single line device with one channel.

Example 2 A single BRI-ISDN line in the computer-centric or phone-centric connection models. The service provider has a number of options as to how it may want to model this, for example:

  • Model the BRI line as a single line device with a pool of two B channels that allows both channels to be combined for establishing 128 kbps calls.
  • Model each B-channel as a separate line device and disallow both channels to be combined into a single 128 kbps channel.
  • Model the BRI connection as two separate line devices, each drawing up to two channels from a shared pool of two B-channels.
  • Model as three line devices, one for each B-channel, and one for the combination. Clearly in the latter two models, resources may be assigned to different line devices at different times.

Example 3 In client/server systems, a pool of telephone ports attached to a server can be shared among multiple client computers over a local area network. The pool can be administered to assign a maximum number of line devices (quota) to each client workstation. It is not unusual for the sum of all quotas to exceed the total number of lines. Furthermore, a given client with a quota equal to 2 may be satisfied by using ports 1 and 2 at one time and ports 7 and 11 at a later time. The service provider for the pool can model this arrangement by giving each client workstation access to two line devices.

Suppose that the configuration of service providers for a given computer is such that this particular service provider gets a DeviceIDBase of 3. This implies that the (fixed) device identifiers for this client are 3 and 4. If the application later calls the TAPI function lineGetDevCaps for device 3 and again for device 4, it should be able to assume that the device capabilities for each of these devices are constant, because that is the Win32 device model. As long as the given computer's service-provider configuration remains constant, the device identifiers that appear at the TSPI level remain constant, even if the server changes port allocations. For server-based devices that are pooled as described in Example 3, this holds only for line devices that have identical device capabilities. Of course, if the given computer's service-provider configuration is changed, such that this service provider gets a different DeviceIDBase, device identifiers change correspondingly.

Example 4 Switch-to-host link.

  • To provide personal telephony to each desktop, the service provider could model the PBX line paired with the computer as a single line device with one channel. Each client computer would have one line device available.
  • Each third-party station could be modeled as a separate line device. This enables the application to control calls on other stations. This solution requires that the application open each line it wants to manipulate or monitor, which may be fine if only a small number of lines is of interest, but may generate a lot of overhead if a large number of lines is involved.
  • The set of all third-party stations could be modeled as a single line device with one address (phone number) assigned to it per station. Only a single device is to be opened, providing monitoring and control of all addresses on the line (all stations). To originate a call on any of these stations, the application only needs to specify the station's address to the operation that makes the call. No extra open operations are required. This modeling does imply that all stations have the same line device capabilities, although their address capabilities could be different.

Note All of these examples are simply different ways that a service provider may choose to implement the mapping of line device behavior onto some physical realization.

The tapi32.dll is notified about changes in the status of a line device with the LINE_LINEDEVSTATE callback message. The tapi32.dll can control line status items for which it wants to be notified with the TSPI_lineSetStatusMessages function. It can determine the complete status of a line device by calling TSPI_lineGetLineDevStatus.


Opening and Closing Line Devices

After performing basic initialization and possibly having retrieved device capabilities, tapi32.dll must open the line device before it can access telephony functions on that line. When a line device is opened successfully, tapi32.dll is returned a handle representing the open line. The TSPI_lineOpen function opens a specified line device for providing subsequent monitoring and/or control of the line. TSPI_lineClose closes a specified line device.

At the TAPI level, a line device can be specified to lineOpen in one of two ways:

  • A specific line device is selected by means of its line device identifier. The lineOpen request opens the specified line device, possibly resulting in a TSPI_lineOpen call to the service provider (that is, if the line was not already open). Applications interested in handling inbound calls typically use specific line devices.
  • The application can specify that it wants to use any line device that has certain properties. The LINEMAPPER indication is used instead of a specific line device identifier. The properties are specified by means of the call parameters that the application intends to use. The tapi32.dll satisfies this Open request with any available line device that supports the specified call parameters, but this may fail. If successful, the caller can determine the line device identifier by calling lineGetID on the handle to the open line device returned by lineOpen.

To support LINEMAPPER selection of lines, the service provider must implement the TSPI_lineConditionalMediaDetection function. This function does two things: (1) it tests a line's ability to support the requested call parameters and media mode, and (2) if successful, it commits the service provider to monitoring for the new media mode. The tapi32.dll uses this function for different line devices to hunt for a line that meets the application's Open requirements.


Version Compatibility

Over time, different versions of tapi32.dll, applications, and service providers for a line or phone may be produced. These new versions can make new definitions, such as for new features, new members in data structures, and new bit fields. Version numbers are therefore necessary to indicate how to interpret various data structures.


Version Negotiation

To allow optimal interoperability of different versions of applications, versions of tapi32.dll itself, and versions of service providers by different vendors, TSPI provides a simple version negotiation mechanism for applications. There are two different versions that need to be agreed on by tapi32.dll and the service provider for each line device. The first is the version number for the Basic and Supplementary Telephony SPI, referred to as the TSPI interface version. The other is for provider-specific extensions, if any, and is referred to as the extension version. The format of the data structures and datatypes used by TSPI's Basic and Supplementary features is defined by the TSPI version, while the extension version determines the format of data structures defined by the vendor-specific extensions.

These two types of version negotiation are handled by two different procedures: TSPI_lineNegotiateTSPIVersion is used to negotiate the TSPI interface version, and TSPI_lineNegotiateExtVersion is used to negotiate the extension version. Extension version negotiation can always be skipped if extensions are not wanted range of version numbers. If these ranges overlap, the service provider must return a value within the overlapping portion of the range as the result of the negotiation. Usually, this should be the highest possible value. If the ranges do not overlap, the two parties are incompatible and the function returns an error.

Results of a negotiation simply indicate that the service provider is willing to operate at a particular version number, but do not commit the service provider to doing so. For example, tapi32.dll can renegotiate to determine an ideal version after having negotiated a possible version. The TSPI interface version is only committed when a line is opened using TSPI_lineOpen and survives until the device is closed. The extension version is committed when the TSPI_lineSelectExtVersion function is called, and survives until the selection is canceled by selecting extension version zero.

Extension version selection can happen many times, including while an extension version is in effect. Because the service provider is committed to the extension version, its range of supported versions narrows to exactly that extension version. For example, consider a service provider that is normally compatible with extension versions 1.0 through 5.5. If version 3.0 is in effect while a caller attempts to negotiate a version within the range 1.0 to 5.5, the negotiation returns 3.0.


Address Formats

An address assigned to a line device is typically selected by its address identifier. Each address identifier corresponds to a directory number through which the address is known to entities that want to make calls to it. Also, making outbound calls typically requires that a directory number be supplied to identify the called party.


Storing Numbers in Electronic Address Books

Many users choose to dial people, fax machines, bulletin boards, and other entities by selecting their names from an address book. The actual number that is dialed depends on the geographic location of the user and the way the line device to be used is connected. For example, a computer may have access to two lines, one connected to a PBX, the other to the telephone company's central office. When making a call to the same party, different numbers may have to be used. (To dial through the PBX, for example, the PC may need to dial '9' to get an outside line, or a different prefix may be needed for a call made through the central office.) Or, a user may make calls from a portable computer and want to use a single, static address book even when calling from different locations or telephony environments. The TAPI address translation capabilities let the user inform the computer of the current location and the desired line device for the call. TAPI then handles any dialing differences, requiring no changes to the user's address book.

A related topic is the handling of international call progress monitoring, which is the process of listening for audible tones such as dial tone, special information tones, busy signals, and ringback tones to determine the state of a call (its progress through the network). Because the cadences and frequencies of call-progress tones vary from country to country, the service provider must know what call progress to follow when making an international outbound call. Therefore, applications specify the destination country code when placing outgoing calls.

To deal with directory numbers, TAPI defines two common formats. One is the canonical address format, the other is the dialable number format. The canonical address format is intended to be a universally constant directory number; it is the directory number one would like to store in the address book, and never change. TAPI contains operations (address translation) to take addresses in the canonical address format and convert them to the dialable number format. A side effect of this conversion process is to extract a country code identifying the target country for the call. All addresses that appear at TSPI have been translated to dialable address format (see Dialable Addresses). Functions that involve dialing include the extracted country code. This country code can be used by the service provider to provide call progress determination that is independent of national boundaries.


Dialable Addresses

The dialable address format describes a number that can be dialed on the given line. A dialable address contains part addressing information and is part navigational in nature. A dialable address is an ASCII string with the following structure:

DialableNumber | Subaddress ^ Name CRLF ...

where:

DialableNumber digits and modifiers 0-9 A-D * # , ! W w P p T t @ $ ? ; delimited by | ^ CRLF or the end of the dialable address string.

Within the DialableNumber, note the following definitions:

0-9 A-D * # | ASCII characters corresponding to the DTMF and/or pulse digits.
! | ASCII Hex (21). Indicates that a hookflash (one-half second on hook followed by one-half second off hook before continuing dialing) is to be inserted in the dial string.
P p | ASCII Hex (50) or Hex (70). Indicates that pulse dialing is to be used for the digits following it.
T t | ASCII Hex (54) or Hex (74). Indicates that tone (DTMF) dialing is to be used for the digits following it.
, | ASCII Hex (27). Indicates that dialing is to be paused. The duration of a pause is device specific and can be retrieved from the line's device capabilities. Multiple commas can be used to provide longer pauses.
W w | ASCII Hex (57) or Hex (77). An uppercase or lowercase W indicates that dialing should proceed only after a dial tone has been detected.
@ | ASCII Hex (40). Indicates that dialing is to "wait for quiet answer" before dialing the remainder of the dialable address. This means to wait for at least one ringback tone followed by several (usually five or more) seconds of silence.
$ | ASCII Hex (24). It indicates that dialing the billing information is to wait for a "billing signal" (such as a credit card prompt tone).
? | ASCII Hex (3F). It indicates that the user is to be prompted before continuing with dialing. The provider does not actually do the prompting, but the presence of the "?" forces the provider to reject the string as invalid, alerting the application to the need to break it into pieces and prompt the user between pieces.
; | ASCII Hex (3B). If placed at the end of a partially specified dialable address string, it indicates that the dialable number information is incomplete and more address information will be provided later. ";" is only allowed in the DialableNumber portion of an address.
| | ASCII Hex (7C), and is optional. If present, the information following it up to the next + | ^ CRLF, or the end of the dialable address string, is treated as subaddress information (as for an ISDN subaddress).

Subaddress | A variably sized string containing a subaddress. The string is delimited by the next + | ^ CRLF or the end of the address string. When dialing, subaddress information is passed to the remote party. It can be such things as an ISDN subaddress or an e-mail address.
^ | ASCII Hex (5E), and is optional. If present, the information following it up to the next CRLF or the end of the dialable address string is treated as an ISDN name.
Name | A variably sized string treated as name information. Name is delimited by CRLF or the end of the dialable address string. When dialing, name information is passed to the remote party.
CRLF | ASCII Hex (0D) followed by ASCII Hex (0A). If present, this optional character indicates that another dialable number is following this one. It is used to separate multiple canonical addresses as part of a single address string (inverse multiplexing).

Note A dialable address can contain other characters such as spaces, parentheses, hyphens, and so on. The service provider must ignore characters that it does not recognize and strip them from the dialable string before passing the address along to hardware (if necessary). TAPI does not filter out such characters.


Calls

Unlike line devices and addresses, calls are dynamic. A call or call appearance represents a connection between two (or more) addresses. The originating address (the caller) is the address from which the call originates, and the destination address (the called) identifies the remote endpoint or station with which the originator wants to communicate.

Zero, one, or more calls can exist on a single address at any given time. A familiar example of multiple calls on a single address is call waiting. During a conversation with one party, a subscriber with call waiting is alerted that another party is trying to call. The subscriber can flash the phone to answer the second caller (which automatically places the first party on hold), and then toggle between the two parties by flashing. In this example, the subscriber has two calls on one address on the line. Because the person at the telephone handset can be talking to only one remote party at a time, only one call is active per line at any point in time. The telephone switch keeps the other calls on hold. With a line able to encompass more than one channel, different configurations can allow multiple active calls on one line at a time.

The Telephony SPI identifies a specific call by means of a call handle, and tapi32.dll and the service provider both assign call handles as required. Because each needs to allocate a data structure to maintain the state information it associates with a call, each has its own handle. At the start of the lifetime of a call, tapi32.dll and the service provider exchange handles with one another. Then when tapi32.dll calls a function to operate on a call, it passes the service provider's handle. Typically, the service-provider designer implements its handles as pointers or array indexes. This allows simple and efficient access to the associated data structure given the handle. The tapi32.dll uses similar techniques to find its associated data structure when the service provider sends it a message that includes a call handle.

The tapi32.dll tells the service provider to dispose of a call handle by calling TSPI_lineCloseCall.


Making Calls

Before an outbound call can be made, tapi32.dll must open the line device. The standard way to make the call is then for tapi32.dll to invoke TSPI_lineMakeCall, specifying the line handle and a dialable destination address. The request first obtains a call appearance on an address on the line, waits for a dial tone, and dials the specified address. If successful, the TAPI handle to the new call is stored by the service provider for subsequent event reports and the service provider's handle to the new call is returned. The tapi32.dll saves the service provider's handle for subsequent requests on the new call.

When making a new call, tapi32.dll has the option of specifying the address on the line where it wants the call to originate. This can be done by specifying the address identifier or by using the corresponding directory number. The latter can be useful in configurations where it is more practical to identify the originating address by its directory number than by its address identifier. If special call setup parameters are to be taken into consideration, tapi32.dll must supply additional information to TSPI_lineMakeCall. Call setup parameters are required when requesting such things as a special bearer mode, a call's bandwidth, a call's expected media mode, user-user information (for ISDN), securing of the call, blocking the sending of a caller identifier to the called party, or automatically taking the phone offhook at the originator and/or the called party.

The tapi32.dll can also use TSPI_lineMakeCall only to allocate a call appearance (or partially dial) and then explicitly perform (or complete) dialing by using TSPI_lineDial. When the number provided is incomplete, dialing the digits can be delayed by placing a ';' (semicolon) at the end of the number. The TSPI_lineMakeCall function makes an outbound call and returns a call handle for the new call. TSPI_lineDial dials (parts of one or more) dialable addresses. Use this operation in all situations where you need to send address information to the switch on an existing call, such as dialing the address of a party to which to transfer a call.

After dialing is complete, call progress information is provided to tapi32.dll in the LINE_CALLSTATE callback message. This enables tapi32.dll to track whether or not the call is reaching the called party.

The dialable number format allows multiple destination addresses to be supplied at once. This can be useful if the service provider offers some form of inverse multiplexing by setting up calls to each of the specified destinations and then managing the information stream as a single high-bandwidth media stream. The tapi32.dll would perceive this as a single call, as it receives only a single call handle representing the aggregate of all the individual phone calls. It is also possible to support inverse multiplexing at the application level. Then the application would establish a series of individual calls and synchronize their media streams.


Call Notification

After tapi32.dll opens a line device and calls TSPI_lineSetDefaultMediaDetection to specify the desired media modes for inbound calls, it can be notified when a call arrives. The service provider informs tapi32.dll of a new incoming call in the LINE_NEWCALL callback message. This message passes the service provider's handle for the call to tapi32.dll. The tapi32.dll returns its handle for the call. The service provider follows this with a LINE_CALLSTATE callback message. For an unanswered inbound call, the call state is offering. tapi32.dll can then invoke TSPI_lineGetCallInfo to find out information about the call. The fact that a call is offered may not necessarily imply that the user is being alerted. A separate LINE_LINEDEVSTATE callback is made with a ringing indication to provide this information to tapi32.dll.

LINE_NEWCALL can fail due to finite-resource limitations. The tapi32.dll may run out of resources to handle a new call under very high traffic conditions. In such a case, tapi32.dll returns NULL instead of a valid call handle, indicating that the newly offered call handle was not successfully received. The service provider can respond by dropping the call or by retrying the LINE_NEWCALL after a scheduling delay. In any case, the service provider must check for this NULL return and must never attempt to pass subsequent messages using the invalid call handle.

The LINE_NEWCALL message and subsequent LINE_CALLSTATE message also notifies tapi32.dll about the existence and state of outbound calls established as a side effect of other calls (for example, when an active call is put on hold and replaced by a new call in dial tone state) or manually by the user (for example, on an attached phone device). The call state of such calls reflects the actual state of the call, which will not be offering. By examining the call state, tapi32.dll can determine whether the call is an inbound call that needs to be answered.

Call information includes (among other things):

  • Bearer mode, rate This is the bearer mode (voice, data) and data rate (in bps) of the call.
  • Media mode The current media mode of the call. Unknown if this information is unknown.
  • Call origin Indicates whether the call originated from an internal caller, an external caller, or unknown.
  • Reason for the call Describes why the call is occurring. Possible reasons are: direct call, transferred from another number, busy-forwarded from another number, unconditionally forwarded from another number, the call was picked up from another number, a call completion request, or a callback reminder. The reason for the call is given as Unknown if this information is not known.
  • Caller-ID Identifies the originating party of the call. This can be in a variety of (name or number) formats, determined by what the switch or network provides.
  • Called-ID Identifies the party originally dialed by the caller.
  • Connected-ID Identifies the party that is actually connected to. This can be different from the called party if the call was diverted.
  • Redirection-ID Identifies to the caller the number to which the call is now diverted (redirected).
  • Redirecting-ID Identifies to the caller the original destination from which the call was diverted (redirected).
  • User-user information User-user information sent by the remote station (ISDN).

Depending on the telephony environment, not all information about a call may be available at the time the call is initially offered. For example, if caller identifier is provided by the network between the first and second ring, the caller identifier is still unknown when the call is first offered. When it becomes known shortly thereafter, a LINE_CALLINFO callback message notifies tapi32.dll about the change in party-identifier information of the call.

If a new call arrives while another call already exists on the line or address, similar notification and call information is supplied following the same mechanism as for any incoming call. If an application does not want any interference for a call from the switch or phone network, it should secure the call. Securing a call can be done at the time the call is made using a parameter of TSPI_lineMakeCall, or later, with the function TSPI_lineSecureCall, when the call already exists. The call is secured from interference by other events until it is disconnected. Securing a call may be useful, for example, when it is feared that certain network tones (such as call waiting) could disrupt a call's media stream, such as fax.

After tapi32.dll is offered a call, it can answer the call using TSPI_lineAnswer. After a call is answered, its state typically transitions to connected and information can be exchanged over it.


Unowned Calls

To prevent unowned calls from being in the telephony system, TAPI drops calls that have been signalled up from a service provider if it cannot identify an application to be the initial owner of the call. In TAPI version 2.0 and later, TAPI calls the TSPI_lineDrop function to drop the call. In Windows 95, TAPI calls the TSPI_lineDropNoOwner function instead if the service provider exports the function.

The service provider can know in advance whether or not there is an application available to take ownership of a new call. TAPI always informs the service provider of the media modes for which there is an application available by using the TSPI_lineSetDefaultMediaDetection function. For example, if a service provider determines that there is an active call on the line having LINEMEDIAMODE_INTERACTIVEVOICE mode, it should check the default media detection before generating the LINE_NEWCALL and LINE_CALLSTATE messages. If the default media detection shows that no application is looking for a LINEMEDIAMODE_INTERACTIVEVOICE call, the service provider should not send the messages because TAPI will immediately drop it. If at some point, TAPI calls the TSPI_lineSetDefaultMediaDetection function to indicate that some application is available to take ownership of the call, the service provider can then send the LINE_NEWCALL and LINE_CALLSTATE messages and the call will not be dropped.


Call Drop

To terminate a call or a call attempt, tapi32.dll can use TSPI_lineDrop on the call. This function disconnects a call, or abandons a call attempt in progress.

If the remote party disconnects a call, the service provider sends a LINE_CALLSTATE message with a call state of disconnected. To clear the call, tapi32.dll must also drop the call by invoking TSPI_lineDrop on the call, which causes the call to be transitioned by the service provider to the idle state.

A call handle remains valid after a call is dropped. This enables tapi32.dll to still call operations such as TSPI_lineGetCallInfo to retrieve information about a call (for example, for logging purposes). The call handle is eventually deallocated by TSPI_lineCloseCall, which shuts down operations for a call and deallocates (invalidates) the call handle.


Call Handles

A handle is a pointer to a pointer, that is, an access to a value, a necessary piece of information, or a resource required in one variable identified in another variable. Call handles access and supply specific variable information requested by TPSI functions.


Pending Call Handles

A service provider is required to create one or more call handles (variables of type HDRVCALL) whenever TAPI calls one of these functions: TSPI_lineMakeCall, TSPI_lineCompleteTransfer, TSPI_lineForward, TSPI_linePickup, TSPI_linePrepareAddToConference, TSPI_lineSetupConference, TSPI_lineSetupTransfer, and TSPI_lineUnpark. When a service provider receives such a call, the service provider must set the variable supplied by TAPI to the value of the handle before returning from the call. TAPI considers this "pending call handle" to be tentatively valid. When the service provider actually creates the call, it must call the ASYNC_COMPLETION callback to formally validate the handle.

If TAPI calls the TSPI_lineCloseCall function before the service provider formally validates a pending call handle, the service provider must stop all further processing associated with the call handle and call the ASYNC_COMPLETION callback function using the error value LINEERR_OPERATIONFAILED.


Async Replies versus Events on New Call Handles

TSPI includes a number of operations that start the lifetime of a call handle. If the service provider returns SUCCESS for such an operation, it must fill in the opaque handle of type HDRVCALL, which it uses for the new call before it returns. The tapi32.dll never performs operations on the call before the matching ASYNC_COMPLETION has been received. If the service provider returns FAILURE, the handle automatically becomes invalid (that is, without TSPI_lineCloseCall). In effect, tapi32.dll treats the handle as "not yet valid" until the asynchronous completion.

The service provider must also treat the handle as "not yet valid" until after the matching ASYNC_COMPLETION is received. In other words, it must not issue any LINEEVENT functions for the new call or include it in call counts in messages or status data structures for the line.

The TAPI level also conforms to these life cycle restrictions; a new call handle is not returned or valid until the matching LINE_REPLY message, and no events for the new call are delivered to the application until after the LINE_REPLY message.

The TSPI operations to which this "start lifetime" principle applies are the following:

TSPI_lineCompleteTransfer
TSPI_lineForward
TSPI_lineMakeCall
TSPI_linePickup
TSPI_linePrepareAddToConference
TSPI_lineSetupConference
TSPI_lineSetupTransfer
TSPI_lineUnpark


Call Handle Manipulation

TAPI provides a number of functions for manipulating call handles, determining the relationship among lines, calls, and address, and so on. Most of this functionality is implemented strictly within tapi32.dll without reference to the service provider, except for TSPI_lineGetCallAddressID. This function retrieves the address identifier of an existing call within its line. Service providers that model a line as a group of address identifiers can choose an unpredictable address for a new inbound or outbound call. This function gives tapi32.dll sufficient information to implement the lineGetNewCalls operation when it is invoked with the LINECALLSELECT_ADDRESS option.


Externally Generated Phone Numbers

A service provider can indicate externally generated phone numbers (that is, numbers for outbound calls generated externally to the computer) by setting the DisplayableAddress, CalledParty, or Comment members in the LINECALLINFO structure when processing the TSPI_lineGetCallInfo function. If TAPI has not saved its own data for these members, it leaves the data set by the service provider unchanged. If TAPI does have cached data for these members, TAPI adds its text to the end of the variable portion of the LINECALLINFO structure and overwrites the size and offset the service provider has put into the fixed portion.

A service provider can also copy an outbound number into the CalledID member. Therefore, logging applications should check the CalledID member on outbound calls if the DisplayableAddress and CalledParty members are empty.


Resource Limitations

After tapi32.dll opens a line device, it can make outbound calls on the line. A successful Open of a line device does not automatically guarantee that the TSPI_lineMakeCall request will succeed. Depending on the environment, a service provider may have limits on the number of concurrent calls on a line. The service provider may return a failure in response to TSPI_lineMakeCall if it is unable to allocate line resources necessary for a call appearance for the desired new outbound call. If other calls exist on the line, these calls would have to be on hold and would typically be forced to remain on hold until tapi32.dll either places the new call on hold or drops the call.

For service providers that model lines as a pool of available channels, these restrictions may not apply, because the service provider may have sufficient channel resources to make a new outbound call, even when other channels in the pool are in use.

Whenever tapi32.dll has opened a line device, it is notified about certain general status and events occurring on the line device or its addresses. These include the line being taken out of service, the line going back in service, the line being under maintenance, or an address becoming in use or going idle. The tapi32.dll will call TSPI_lineClose on the line device handle after all client applications have called lineClose on the API.

In certain environments, it may be desirable for a line device that is currently open to be forcibly reclaimed (possibly by the use of a small control application) from tapi32.dll control. This might be required, for example, if the service provider detects a situation where the line must be taken out of service or a PBX administrator decides to preempt use of a line. If a service provider encounters such a situation, it can issue a LINE_CLOSE message to tapi32.dll for the open line device that was forcibly closed.


Setting a Terminal for Phone Conversations

The user's computer may have access to multiple devices that are selectable by the user and used to conduct interactive voice conversations. First, there is the phone device itself, complete with lamps, buttons, display, ringer, and voice I/O device (handset, speakerphone, headset). The user's computer may also have a separate voice I/O device (such as a headset or a microphone/speaker combination attached to a sound card) for use with phone conversations.

TSPI enables the user to select where to route the information that the switch sends over the line, address, or call. The switch normally expects this to be one of its phone sets, and sends ring requests, lamp events (for stimulus phones), display data, and voice data as appropriate. The phone in turn sends hookswitch events, button press events (for stimulus phones), and voice data back to the switch.

The line portion of TSPI makes lamp events, display events, and ring events available, either as functional return codes to the various line operations in TSPI, or as unsolicited functional call status messages that are sent to the application callback. The service provider implementation is responsible for mapping between the functional TSPI level and the underlying stimulus or functional messages used by the telephony network. In functional telephony environments, TSPI functions are mapped to the functional protocol.

Using the TSPI_lineSetTerminal function, tapi32.dll can control the routing of different low-level events exchanged between the switch and the station; it can also decide not to route some of these low-level events to a device. The routing of the different classes of events can be individually controlled. For example, the media stream of a call (such as voice) can be sent to any transducer device if the service provider and hardware are capable of doing so. Ring events from the switch to the phone can be mapped into a visual alert on the computer's screen or they can be routed to a phone device. Lamp events and display events can be ignored or routed to a phone device (which appears to behave as a normal phone set). Finally, button presses at a phone device may or may not be passed on to the line. In any case, this routing of low-level signals from the line does not affect the operation of TSPI's line portion, which always maps the low-level events to their functional equivalent. Applications can consult a line's device capabilities to determine the terminals it has available.

In other words, the TSPI_lineSetTerminal function specifies the terminal device to which the specified line, address events or call media stream events are routed. Separate terminals can be specified for each event class. Event classes include lamps, buttons, display, ringer, hookswitch, and media stream.


Supplementary Line Services

Supplementary line services are advanced telephony features associated with PBXs, Centrex, and ISDN. Service providers may choose to implement these features to suit the design of custom products, but supplementary line services are optional.

This section describes the supplementary services used with line devices. For convenience, they are grouped into general functional categories.


Bearer Mode and Rate

The notion of bearer mode corresponds to the quality of service requested from the network for establishing a call. It is important to keep the concept of bearer mode separate from that of media mode. The media mode of a call describes the type of information that is exchanged over a specific call of a given bearer mode. As an example, the analog telephone network or public switched telephone network (PSTN) only provides 3.1 kHz voice grade quality of service-this is its bearer mode. However, a call with this bearer mode can support a variety of different media modes such as voice, fax, or data modem. In other words, media modes require certain bearer modes. TSPI only manages the bearer modes by passing the bearer mode parameters on to the network. Media modes are fully managed through the appropriate media mode functions, although some limited support is provided in TSPI.

The bearer mode of a call is specified when the call is set up, or is provided when the call is offered. With line devices able to represent channel pools, it is possible for a service provider to allow calls to be established with wider bandwidth. The rate (or bandwidth) of a call is specified separately from the bearer mode, allowing an application to request arbitrary data rates.

The bearer modes defined in Win32 Telephony are:

  • Voice Regular 3.1 kHz analog voice service. Bit integrity is not assured.
  • Speech G.711 speech transmission on the call.
  • Multiuse As defined by ISDN.
  • Data Unrestricted data transfer. The data rate is specified separately.
  • Alternate speech and data The alternate transfer of speech and unrestricted data on a call (ISDN).
  • Non-call-associated signaling This provides a clear signaling path from the application to the service provider.

Although support for changing a call's bearer mode or bandwidth is limited in networks today, the SPI provides an operation to request a change in specific call parameters, namely the call's bearer mode and/or data rate. The operation is TSPI_lineSetCallParams.


Monitoring

Monitoring is a service-provider defined feature that detects signals that indicate other media. For example, one application can be playing an outgoing "leave a message" voice message while the incoming call starts sending a fax "calling" tone and waits for a handshake. In order not to lose the fax call, the local application monitors for this tone while playing the voice message.

Monitoring comprises media monitoring, digit monitoring, and tone monitoring.


Media Monitoring

When a call is in the connected state, information can be transported over the call. A call's media mode provides an indication of the type of information (for example, the datatype or higher-level protocol) of this media stream. TSPI allows tapi32.dll to be provided with a callback notification about changes in a call's media mode. The notification provides an indication of the call's new media mode. The service provider decides how it wants to make this determination.

For example, the provider could use signal processing of the media stream to determine media mode, or it could rely on distinctive ringing patterns assigned to different media streams, or on information elements passed in an out-of-band signaling protocol. Independent of how the media mode is determined, tapi32.dll is simply informed about media mode changes on a call.

The media modes defined by Win32 Telephony include:

  • Unknown The media mode of the call is not currently known; the call is unclassified.
  • Interactive voice Voice energy was detected on the call, and the call is handled as an interactive voice call with a person at the application's end.
  • Automated voice Voice energy was detected on the call, and the call is handled as a voice call but with no person at the application's end, such as with an answering-machine application. When the service provider cannot distinguish between interactive and automated voice on an incoming call, it should treat or report the call as interactive voice.
  • Data modem A modem session on the call. Current modem protocols require the called station to initiate the handshake. For an inbound data modem call, the application can typically make no positive detection. The service provider chooses how to make this determination. For example, a period of silence just after answering an inbound call may be used as a heuristic to decide that this might be a data modem call.
  • G3 fax A group 3 fax session on the call.
  • TDD The call's media stream uses the Telephony Devices for the Deaf (TDD) protocol.
  • G4 fax A group 4 fax session on the call.
  • Digital data A digital data stream of unspecified format.
  • Teletex, Videotex, Telex, Mixed These correspond to the telematic services of the same names.
  • ADSI An Analog Display Services Interface session on the call. ADSI enhances voice calls with alphanumeric information downloaded to the phone and the use of soft buttons on the phone.

Media monitoring can be enabled and disabled on a specified call with TSPI_lineMonitorMedia. The tapi32.dll specifies which media modes it is interested in monitoring. If enabled, the detection of a media mode causes tapi32.dll to be notified in the LINE_MONITORMEDIA callback message, which notifies tapi32.dll about a media mode change. The callback provides the call handle on which the media mode change was detected as well as the new media mode.

There is a distinction between the media mode of a call as reported by TSPI_lineGetCallInfo and the media mode event reports in LINE_MONITORMEDIA messages. A call's media mode is determined exclusively by tapi32.dll and is not automatically changed by media monitoring events.

Default media mode monitoring for calls is performed for the media modes for which the line device has been set. This allows an inbound call's media mode to be determined early based on what is needed by tapi32.dll.

Note The scope of a call's media monitoring of a call is bound by the lifetime of the call. Media monitoring on a call ends as soon the call disconnects or goes idle.

The tapi32.dll can obtain device identifiers for various Win32 device classes associated with an opened line by invoking TSPI_lineGetID. This function takes a line handle, address, or call handle and a device class description. It returns the device identifier for the device of the given device class that is associated with the open line device, address, or call. If the device class is tapi/line, the device identifier of the line device is returned. If the device class is mci wave, the device identifier of an mci waveaudio device (if supported) is returned that allows the manipulation such as recording or playback of audio over the call on the line.

The tapi32.dll can use the returned device identifier with the corresponding media API to query the device's capabilities and subsequently open the media device. For example, if the tapi32.dll client application needs to use the line as a waveform device, it first needs to call waveInGetDevCaps and/or waveOutGetDevCaps to determine the waveform capabilities of the device. The typical waveform data format supported by telephony in North America is 8-bit m-law at 8,000 samples per second, although the wave device driver can convert this sample rate and companding to other more common multimedia audio formats.

To subsequently open a line or address for audio playback using the waveform API, an application calls the waveOutOpen function. The implementation of the waveOutOpen call is device-specific, and each implementation has a number of options for implementing this function. If the call is not answered at the time the function is invoked, for example, the waveOutOpen driver may return an error code message to the application allowing it to display a dialog box stating that "the phone is ringing." This is similar to requesting a CD to play back audio when no compact disc is in the player, and the existing definition of the waveform APIs should handle the situation.


Digit Monitoring

Digit monitoring monitors the call for digits. TSPI enables signaling of digits in two modes:

  • Pulse Digits are signaled as pulse/rotary sequences. For detection, these pulses manifest themselves as nothing more than sequences of audible clicks. Valid pulse digits are '0' through '9'.
  • DTMF Digits are signaled as DTMF (Dual Tone Multi-Frequency) tones. Valid DTMF digits are '0' through '9', 'A'. 'B', 'C', 'D', '*', and '#'. Both the beginning and the down edge of DTMF digits can be monitored.

Digit monitoring can be enabled or disabled on a specified call with TSPI_lineMonitorDigits. If enabled, all detected digits cause tapi32.dll to be notified in the LINE_MONITORDIGITS callback message. The callback provides the call handle on which the digit was detected as well as the digit value and the digit mode. The scope of digit monitoring is bound by the lifetime of the call. Digit monitoring on a call ends as soon the call disconnects or goes idle.


Tone Monitoring

Tone monitoring monitors the media stream of a call for specified tones. A tone is described by its component frequencies and cadence. An implementation of TSPI may allow several different tones to be monitored simultaneously. TSPI uses a two-level identification scheme to identify the tones monitored. There is a tone group and an application-defined tag field, identifying a specific tone within a group.

The tapi32.dll can request monitoring for multiple concurrent tone groups, which the service provider should support if it has sufficient resources. Groups are monitored or canceled as a group; there is no finer granularity. Tone monitoring is enabled/disabled on a per-call basis using TSPI_lineMonitorTones.

When tones are detected, the LINE_MONITORTONE callback message notifies The tapi32.dll. This message includes the tone-group identifier and the application-specific identifier within that tone group to identify the tone that was detected. An application can tag each tone in order to be able to differentiate tones for which it requests detection. The scope of tone monitoring is bound by the lifetime of the call. Tone monitoring on a call ends as soon the call disconnects or goes idle.

The monitoring of tones, digits, or media modes often requires resources that the service provider may have only in finite amounts. A request for monitoring may be rejected if resources are not available. For the same reason, client applications should disable any monitoring that is not needed.


Media Control

The tapi32.dll can request the execution of a limited set of media control operations on the call's media stream triggered by telephony events. Although the tapi32.dll clients normally use the media function specifically defined for the media mode, media control can yield a significant performance improvement for client/server implementations because simple "detect/control" sequences can be offloaded to the server. The operation TSPI_lineSetMediaControl allows tapi32.dll to specify a list of tuples specifying a telephony event and the associated media-control action, and thus sets up a call's media stream for media control. The telephony events that can trigger media control activities are:

  • Detection of a digit The tapi32.dll provides a list of specific digits and the media control action each of them triggers.
  • Detection of a media mode The tapi32.dll provides a list of media modes and the media control actions a transition into the media mode triggers.
  • Detection of a specified tone The tapi32.dll specifies a list of tones and the media control action each tone detection triggers.
  • Detection of a call state The tapi32.dll specifies a list of call states and the media control action each transition to the call state triggers.

The following media control actions are defined generically for the different media modes. Not all media streams can provide meaningful interpretations of the media control actions. The operations should map well to audio streams.

  • Start Starts the media stream.
  • Reset Resets the media stream.
  • Pause Stops or pauses the media stream.
  • Resume Starts or resumes the media stream.
  • Rate up Increases the rate (speed) of the media stream by an implementation-defined amount.
  • Rate down Decreases the rate (speed) of the media stream by an implementation-defined amount.
  • Rate normal Returns the rate (speed) to normal.
  • Volume up Increases the volume (amplitude) of the media stream.
  • Volume down Decreases the volume (amplitude) of the media stream.
  • Volume normal Returns the volume (amplitude) to normal.

The scope of media control is bounded by the lifetime of the call. Media control on a call ends as soon the call disconnects or goes idle. Only a single media control request can be outstanding on a call across all applications.


Digit Gathering

Besides enabling digit monitoring and being notified of digits one at a time, tapi32.dll can also request that multiple digits be collected in a buffer. Only when the buffer is full or when some other termination condition is met is tapi32.dll notified. Digit gathering is useful for functions such as credit card number collection. tapi32.dll invokes TSPI_lineGatherDigits, specifying a buffer to fill with digits. Digit gathering terminates when one of a number of conditions is true.

  • The requested number of digits has been collected.
  • One of multiple termination digits is detected. The termination digits are specified to TSPI_lineGatherDigits, and the termination digit is placed in the buffer as well.
  • One of two timeouts expires. The timeouts are a first digit timeout, specifying the maximum duration before the first digit must be collected, and an interdigit timeout, specifying the maximum duration between successive digits.
  • Digit gathering is canceled explicitly by invoking TSPI_lineGatherDigits again with either another set of parameters (as with a new buffer) to start a new gathering request or by using a NULL digit buffer parameter to simply cancel.

When terminated for whatever reason, a LINE_GATHERDIGITS message is sent to the application that requested the digit gathering.

Note Only a single digit gathering request can be outstanding on a call at any given time.

Digit gathering and digit monitoring can be enabled on the same call at the same time. In that case, tapi32.dll receives a LINE_MONITORDIGITS message for each detected digit and a separate LINE_GATHERDIGITS message when the buffer is sent back.


Generating Inband Digits and Tones

Information can be transmitted over a call that is in the connected state. Two functions are provided that allow end-to-end inband signaling between tapi32.dll and remote station equipment such as an answering machine. One function is TSPI_lineGenerateDigits, which signals digits over the voice channel on a call. Digits can be signaled as either rotary/pulse sequences or as DTMF tones. The other function is TSPI_lineGenerateTone, which enables tapi32.dll to generate one of a variety of multifrequency tones over the media stream on a call. This generates telephony tones, such as ringback, beep, busy, as well as arbitrary multifrequency multicadenced tones.

Only one digit or tone generation can be in progress on a call at one time. When digit or tone generation completes, a LINE_GENERATE message is sent to tapi32.dll. In the case of generation of multiple digits, only a single message is sent back after all digits are generated. Calling TSPI_lineGenerateDigits or TSPI_lineGenerateTone while digit or tone generation is in progress aborts the generation currently in progress and sends the LINE_GENERATE message to tapi32.dll with a cancel indication.


Call Accept, Reject, and Redirect

In environments like ISDN, call offering is separate from alerting. On an ISDN network, call offering is the process of sending a call-setup message from the switch. This occurs before ringing, so the call can be redirected before it is answered. The lineAccept function means "start ringing" for ISDN. For POTS, it means that some application has accepted responsibility for the call and has presented it to the user.

After a call has been offered to tapi32.dll, a time window exists during which tapi32.dll has a number of options:

  • tapi32.dll can simply answer the call using TSPI_lineAnswer.
  • tapi32.dll can accept the call using TSPI_lineAccept, which also initiates alerting to the caller (as ringback), and to the called party (as ring).
  • tapi32.dll can reject the offering call using TSPI_lineDrop. The call remains valid but transitions to the idle state.
  • tapi32.dll can redirect the call using TSPI_lineRedirect, which deflects the offering call to another address. The call remains valid but transitions to the idle state.


Call Hold

Most PBXs can associate multiple calls with a single line. A call can be placed on hard hold. This frees up the user's line/address to make other calls. tapi32.dll can place a call on hard hold by invoking TSPI_lineHold. tapi32.dll can retrieve a call on hold by invoking TSPI_lineUnhold.

Hard hold is different from a consultation hold. A call is automatically placed on consultation hold, for example, when it is prepared for transfer or conference.


Call Transfer

The Telephony SPI provides two mechanisms for call transfer: blind transfer and consultation transfer.

  • Blind transfer (or single-step transfer) An existing call is transferred to a specified destination address in one phase using TSPI_lineBlindTransfer. This function transfers a call that was set up for transfer to another call.
  • Consultation transfer The existing call is first prepared for transfer using TSPI_lineSetupTransfer. This places the existing call on consultation hold, and identifies the call as the target for the next transfer completion request. TSPI_lineSetupTransfer also allocates a consultation call that can be used to establish the consultation call with the party to be transferred to. The tapi32.dll can dial the extension of the destination party on the consultation call (using TSPI_lineDial), or it can drop and deallocate the consultation call and instead activate an existing held call (using TSPI_lineUnhold), if supported by the switch.

While the initial call is on consultation hold and the consultation call is active, tapi32.dll can toggle between these calls with TSPI_lineSwapHold. It swaps the active call with the call currently on consultation hold.

Finally, tapi32.dll completes the transfer in one of two ways using TSPI_lineCompleteTransfer:

  • Transfer the call on transfer hold to the destination party. Both calls are cleared from the line; they transition to the idle state, but they remain valid.
  • Enter a three-way conference. A new call handle is created to represent the conference and this handle is returned to tapi32.dll.


Conference Call

Conference calls are calls that include more than two parties simultaneously. They can be set up using either a switch-based conference bridge or an external server-based bridge. Typically, only switch-based conferencing allows the level of conference control provided by TSPI. In server-based conference calls, all participating parties dial into the server, which mixes the media streams together and sends each participant the mix. There may be no notion of individual parties in the conference call, only that of a single call between the application and the bridge server.

A conference call can be established in a number of ways, depending on device capabilities:

  • A conference call can start out as a regular two-party call, that is, a call established with TSPI_lineMakeCall. After the two-party call exists, additional parties can be added, one at a time. Preparing to add the third party establishes the conference call using TSPI_lineSetupConference. This operation takes the original two-party call as input, allocates a conference call, connects the original call to the conference, and allocates a consultation call whose handle is returned to tapi32.dll.
  • tapi32.dll can then use TSPI_lineDial on the consultation call to establish a connection to the next party to be added. TSPI_lineDrop can be used to abandon this call attempt. The third party is added with TSPI_lineAddToConference, which specifies both the conference call and the consultation call.
  • A three-way conference call can be established by resolving a transfer request for a three-way conference. In this scenario, a two-party call is established as either an inbound or outbound call. Next the call is placed on transfer hold with TSPI_lineSetupTransfer which returns a consultation call handle. After a period of consultation, tapi32.dll may have the option to resolve the transfer setup by selecting the three-way conference option, which conferences all three parties together in a conference call using TSPI_lineCompleteTransfer with the conference option (instead of the transfer option). Under this option, a conference call handle representing the conference call is allocated and returned to the application.
  • A conference call may need to be established with TSPI_lineSetupConference without an existing two-party call. This returns a handle for the conference call, and allocates a consultation call. After a period of consultation, the consultation call can be added using TSPI_lineAddToConference. Additional parties are added with TSPI_linePrepareAddToConference followed by TSPI_lineAddToConference.

To add additional parties after a conference call exists, tapi32.dll uses TSPI_linePrepareAddToConference, which specifies the conference call handle and returns a consultation call handle. After the consultation call exists, it can be added using TSPI_lineAddToConference (as described earlier).

After a call becomes a member of a conference call, the member's call state becomes conferenced. The state of the conference call typically becomes connected. The call handle to the conference call and all the added parties remain valid as individual calls. LINE_CALLSTATE events can be received about all calls, for example, if one of the members disconnects by hanging up, an appropriate call state message can inform the application of this fact; such a call is no longer a member of the conference.

As is the case with call transfer, the application may toggle between the consultation call and the conference call using TSPI_lineSwapHold.

The tapi32.dll can use the call handle for the member calls to later remove any or all members from the conference, and it does this by invoking TSPI_lineRemoveFromConference on the call handle. This operation is not commonly available in its fully general form. Some switches may not allow it at all, or only allow the most recently added party to be removed. The line's device capabilities describe which type of TSPI_lineRemoveFromConference is possible.


Removing a Party

When canceling the consultation call to the third party on a conference call or when removing the third party in a previously established conference call, the service provider (and switch) can release the conference bridge and revert the call back to a normal two-party call. If this is the case, the call whose handle is passed (in an invocation of the function TSPI_linePrepareAddToConference) with hConfCall transitions to the idle state, and the only remaining participating call transitions to the connected state.


Child Conference Calls

Service providers should remove conference children from the conferenced state (either idle or some other call state) prior to putting the conference parent call in LINECALLSTATE_IDLE. Otherwise, the children remain in the linked list of conference children, causing problems when TAPI closes the conference in response to a call to the TSPI_lineCloseCall function for the parent conference call.


Call Park

Two forms of call parking are provided: directed call park and nondirected call park. In directed call park, the application specifies the destination address where the call is to be parked. This roughly behaves like a call transfer to the destination address, but it doesn't alert or time out as a transfer would.

In nondirected call park, the switch returns to tapi32.dll the address where it parked the call. In either case, the TSPI_linePark function is used to park a given call at another address.A parked call can later be retrieved. The tapi32.dll specifies the park address to TSPI_lineUnpark, which returns a call handle to the unparked call (it retrieves a parked call). Appropriate LINE_CALLSTATE messages are sent to tapi32.dll as the call is reconnected.


Call Forwarding

Forwarding affects the treatment by the switch or network of incoming calls destined for a given address. The tapi32.dll can specify call forwarding conditions based on origin of call (internal, external, selective based on caller ID), status of the address (busy, no answer, unconditional), and destination address where calls are to be forwarded. When the specified conditions are met for an incoming call, the switch deflects the incoming call to the specified destination number. Because the switch performs the forwarding action, tapi32.dll typically does not know when a call is forwarded.

The TSPI_lineForward function provides a combination of call forwarding and do-not-disturb features. TSPI_lineForward also cancels any or all of the forwarding requests currently in effect. Some switches require that a call be established to the forwarding address in order for call forwarding to be initiated. On such systems, TSPI_lineForward allocates a consultation call and returns the handle for it to tapi32.dll. The consultation call can be used as any other call. After the connection is established, forwarding confirmation is received from the switch, the call is dropped (using TSPI_lineDrop), and forwarding is in effect. A LINE_ADDRESSSTATE message with a forwarding indication informs tapi32.dll about changes in the forwarding status of an address.

It may be impossible for a service provider to know at all times what forwarding is in effect for an address. Forwarding can be canceled or changed in ways that make it impossible for a service provider to be informed of it.


Call Pickup

Call pickup allows tapi32.dll to answer a call that is alerting at another address. The tapi32.dll invokes TSPI_linePickup by identifying the target of the pickup, and is returned a call handle for the picked-up call. (The TSPI_linePickup function picks up a call that is alerting at another number.) There are several ways to specify the target of the pickup request. First, specify the address (extension) of the alerting party. Second, if no extension is specified and the switch allows it, tapi32.dll can pick up any ringing phone in its pickup group. Third, some switches require a group identifier to identify the group to which the ringing extension belongs.

After the call is picked up, the call is diverted to tapi32.dll, and tapi32.dll is also sent appropriate LINE_CALLSTATE messages for the call. The tapi32.dll can invoke TSPI_lineGetCallInfo to find out information about the picked-up call, if provided by the switch.


Call Completion

When making an outbound call, the unavailability of certain resources can prevent the call from reaching the connected state, as when the destination party is busy or doesn't answer. Unavailable resources include trunk circuits as well as the destination party's station. TSPI_lineCompleteCall allows tapi32.dll to specify how it wants to complete a call that cannot be completed normally, and as a result, generates a call completion request. The tapi32.dll has the following options:

  • Camp-on queues the call until the call can be completed.
  • Call back requests the called station to return the call when it returns to idle. Answering the callback can automatically reinitiate (redial) the connection request.
  • Intrude allows tapi32.dll to barge in on the existing call.
  • Message (also known as "leave word calling") allows tapi32.dll to send one of a small number of predefined messages to the destination. These messages can be text shown on the phone's display, a voice message left for the user, and so on.

A call completion request can be canceled with TSPI_lineUncompleteCall. Multiple call completion requests can potentially be outstanding for a given address at any one time. To identify individual requests, the implementation returns a completion identifier. When a call completion request completes and results in a new call, the call completion identifier is available in the LINECALLINFO data structure returned by TSPI_lineGetCallInfo. Canceling a call completion request in progress also uses this call completion identifier.


Extended Line Services

Extended line services (or device-specific line services) include all service-provider defined extensions to TSPI. TSPI defines a mechanism that enables service-provider vendors to extend the Telephony SPI using device-specific extensions. TSPI only defines the extension mechanism, and by doing so provides access to device-specific extensions, but TSPI does not define their behavior. Behavior is completely defined by the service provider.

The Telephony SPI consists of scalar and bit flag constant definitions, data structures, functions, and callback messages. Procedures are defined that enable a vendor to extend most of these as follows.

For extensible scalar data constants, a service-provider vendor can define new values in a specified range. As most data constants are DWORDs, typically the range 0x00000000 through 0x7FFFFFFF is reserved for common future extensions, while 0x80000000 through 0xFFFFFFFF are available for vendor-specific extensions. The assumption is that a vendor would define values that are natural extensions of the datatypes defined by TSPI.

For extensible bit flag data constants, a service-provider vendor can define new values for specified bits. As most bit flag constants are DWORDs, typically a specific number of the lower bits are reserved for common extensions while the remaining upper bits are available for vendor-specific extensions. Common bit flags are assigned from bit zero up; vendor-specific extensions should be assigned from bit 31 down. This provides maximum flexibility in assigning bit positions to common extensions versus vendor-specific extensions. A vendor is expected to define new values that are natural extensions of the bit flags defined by TSPI.

Extensible data structures have a variably sized field that is reserved for device-specific use. Being variably sized, the service provider decides the amount of information and the interpretation. A vendor that defines a device-specific field is expected to make these natural extensions of the original data structure defined by TSPI.

Two functions, TSPI_lineDevSpecific and TSPI_lineDevSpecificFeature, and four related messages, LINE_DEVSPECIFIC, LINE_CALLDEVSPECIFIC, LINE_DEVSPECIFICFEATURE, and LINE_CALLDEVSPECIFICFEATURE, offer a vendor-specific extension mechanism. The TSPI_lineDevSpecific operation and associated LINE_DEVSPECIFIC and LINE_CALLDEVSPECIFIC messages allow the tapi32.dll client application to access device-specific line, address, or call features that are unavailable in the Basic or Supplementary Telephony services. The parameter profile of the TSPI_lineDevSpecific function is generic in that little interpretation of the parameters is made by TSPI. Device-handle parameters have TSPI-defined meanings and are translated appropriately between the application and the service provider. Generic parameters are simply passed through unmodified. The interpretation of the generic parameters is defined by the service provider and must be understood by any applications that use them. An application that relies on device-specific extensions generally does not work with other service providers. However, applications written entirely to the Basic and Supplementary Telephony services should work with the extended service provider.

The tapi32.dll implementation of the device-specific functions and messages is "pass-through." The tapi32.dll does not examine or modify the generic device-specific parameters and buffers, but it does map application-level opaque handle values (used at the TAPI level) to service-provider-level opaque handle values (used at the TSPI level).

Regarding handle translation, the passthrough nature of the generic parts of device-specific extensions has an imporant consequence. A service provider has no way to relate the handles used at the TSPI level to those at the TAPI level except by passing them through the predefined handle parameters and fields. Any handle put into the generic extension area is untranslated by tapi32.dll as it is passed between application and service provider. The designer of a service-provider extension should generally not define extensions that pass handles in this way.

The appropriate approach when defining a device-specific extension that must refer to specific devices without using handles is to refer to them using their absolute device identification. The device identifier used in opening a line at the TAPI level, for example, is strictly the same value that is used at the TSPI level to open the line. Similarly, a (line device identifier, address identifier) tuple that uniquely identifies an address at the TAPI level uses the same values to identify the same thing at the TSPI level.

For convenience, a more specialized escape function is also provided. It is similar to TSPI_lineDevSpecific, but places interpretation on some of the parameters. The TSPI_lineDevSpecificFeature function and associated LINE_DEVSPECIFICFEATURE and LINE_CALLDEVSPECIFICFEATURE messages allow tapi32.dll to emulate button presses at the line's feature phone. As feature phones and the meanings of their buttons are vendor-specific, feature invocation using TSPI_lineDevSpecificFeature is also vendor specific.

To summarize, the TSPI_lineDevSpecificFeature function is a device-specific escape function to allow sending switch features to the switch. The LINE_CALLDEVSPECIFICFEATURE message is a device-specific message sent to the application's callback as an indication of call-related features sent to the switch. LINE_DEVSPECIFICFEATURE is a device-specific message sent to the application's callback as an indication of line-related features sent to the switch.

There is no central registry for manufacturer identifiers. Instead a unique identifier generator called extidgen.exe is made available as part of TSPI. The vendor that designs a set of device-specific extensions uses this utility to obtain a unique identifier for those extensions.


Phone Devices

Telephony defines a device that supports the phone device class as one that includes some or all of the following elements:

  • Hookswitch/transducer This is a means for audio input and output. A phone device can have several transducers, which can be activated and deactivated (taken offhook or placed onhook) under application or manual user control. Telephony identifies three types of hookswitch devices common to many phone sets:

    Handset The traditional mouth-and-ear piece combination that must be manually lifted from a cradle and held against the user's ear.

    Speakerphone Enables the user to conduct calls hands-free. The speakerphone may be internal or external to the phone device. The speaker part of a speakerphone allows multiple listeners.

    Headset Enables the user to conduct calls hands-free.

    A hookswitch must be offhook to allow audio data to be sent to and/or received by the corresponding transducer.

  • Volume control/gain control/mute Each hookswitch device is the pairing of a speaker and a microphone component. Telephony provides for volume control and muting of speaker components and for gain control or muting of microphone components.
  • Ringer A means for alerting users, usually through a bell. A phone device may be able to ring in a variety of modes or patterns.
  • Display A mechanism for visually presenting messages to the user. A phone display is characterized by its number of rows and columns.
  • Buttons An array of buttons. Whenever the user presses a button on the phone set, a report is generated indicating that button press. Button-Lamp identifiers identify a button and lamp pair. Of course, it is possible to have button-lamp pairs with either no button or no lamp. Button-lamp identifiers are integer values that range from 0 to the maximum number of button-lamps available on the phone device, minus one. Each button belongs to a button class. Classes include call appearance buttons, feature buttons, keypad buttons, and local buttons.
  • Lamps An array of lamps (such as LEDs) that are individually controllable. Lamps can be lit in different modes by varying the on and off frequency. The button-lamp identifier identifies the lamp.
  • Data areas Memory areas in the phone device where instruction code or data can be downloaded to and/or uploaded from. The downloaded information can affect the behavior (or in other words, program) the phone device.

Telephony allows an application to monitor and control elements of the phone device. The most useful elements for an application are the hookswitch devices. The phone set can act as an audio I/O device (to the computer) with volume control, gain control, and mute; a ringer (for alerting the user); data areas (for programming the phone); and perhaps a display, though the computer's display is more capable. TheTSPI application should not directly control or use phone lamps or phone buttons. Because lamp and button capabilities vary widely among phone sets, the application could be tailored, unwittingly, to specific phone sets.

There is no guaranteed core set of services supported by all phone devices as there is for line devices (the Basic Telephony services). Therefore, before a phone device can be used, its exact capabilities must first be determined. Telephony capability varies with the configuration (client versus client/server), the telephone hardware, and the service-provider software. Applications should make no assumptions as to what telephony capabilities are available.

The capabilities of a phone device are determined by a call to the TSPI_phoneGetDevCaps function. This function queries a specified phone device to determine its telephony capabilities. With a call to this function, the service provider should fill in all the members of the PHONEBUTTONINFO data structure except dwTotalSize, which is filled in by tapi32.dll. The service provider must not overwrite the dwTotalSize member.

A phone's device capabilities indicate which of these elements exist for each phone device present in the system and what their capabilities are. Although strongly oriented towards real-life telephone sets, this abstraction can provide a meaningful implementation (or subset thereof) for other devices as well. Take as an example a separate headset directly connected and controllable from the computer and operated as a phone device. Hookswitch changes can be triggered by detection of voice energy (offhook) or a period of silence (onhook); ringing can be emulated by the generation of an audible signal into the headset; a display can be emulated through text-to-speech conversion.

A phone device need not be realized in hardware, but can instead be emulated in software using a mouse- or keyboard-driven graphical user interface and the computer's speaker or sound system. Such a soft phone can be an application that uses TAPI. It can also be a service provider, which can be listed as a phone device available to other applications through TAPI, and as such is assigned a phone device identifier.


Basic Phone Services

Basic phone services are the core set of services supported by all phone devices. Because basic phone services are service-provider defined, there is much variety in the core set.


Phone SPI Initialization

As part of the phone device abstraction defined by TSPI, tapi32.dll and the service provider must first undergo basic initialization. This basic initialization is accomplished both for the line and phone halves of the interface by the same set of steps. The first of these steps is interface version negotiation. The tapi32.dll performs this by calling the TSPI_lineNegotiateTSPIVersion function. This function is usually used to negotiate on behalf of an individual line device; different line devices within the same service provider may operate according to different interface versions. The tapi32.dll passes a special reserved device identifier value, INITIALIZE_NEGOTIATION , to indicate that it is negotiating an overall interface version for initialization functions that affect the entire service provider, both for lines and phones.

The result of this negotiation is passed to subsequent procedures until a phone device is opened. At that time, the phone device becomes committed to a particular interface version. This interface version is implicit until the phone is closed, and does not need to be passed to subsequent functions that operate on an opened phone.

Following overall interface version negotiation, tapi32.dll calls the TSPI_providerInit function. This function initializes the service provider, also giving it parameters required for subsequent operation. These parameters include the following:

  • dwPermanentProviderID Specifies the permanent identifier of the service provider being initialized, unique within the service providers on this system.
  • dwLineDeviceIDBase Specifies the lowest device identifier for the line devices supported by this service provider.
  • dwPhoneDeviceIDBase Specifies the lowest device identifier for the phone devices supported by this service provider. Devices of the telephony phone device class are identified by integers starting from zero. This range of identifiers is contiguous across the full range of phone devices. Because there may be multiple service providers managing phone devices in a single system, each service provider gets a contiguous portion of the total range. This parameter tells the service provider the lowest value in its portion of the range. The service provider, rather than tapi32.dll, is responsible for mapping this variable range to its own internal device identifiers. This gives the service-provider vendor sufficient flexibility to use device identifiers in device-specific extensions if it wants. Because the service provider knows what device identifiers appear in the TAPI-defined parameters and data structures, it can use consistent device identifiers in device-specific extension parameters and data structures.
  • dwNumLines Specifies how many line devices this service provider supports.
  • dwNumPhones Specifies how many phone devices this service provider supports.
  • lpfnCompletionProc Specifies the procedure the service provider calls to report completion of all asynchronously operating procedures on line and phone devices.

Following TSPI_providerInit, normal operations such as opening phones can be carried out.


Opening and Closing Phone Devices

After performing basic initialization and possibly retrieval of device capabilities, tapi32.dll must open the phone device before it can access functions on that phone. After a phone device is successfully opened, tapi32.dll is returned a handle representing the open phone. The function TSPI_phoneOpen opens the specified phone device prior to providing access to functions on the phone. TSPI_phoneClose closes a specified phone device.

A phone device is identified to TSPI_lineOpen by means of its device identifier. This function returns a handle to an open phone. A handle to an open phone device is used in other operations to identify the open phone device. The only functions on phone devices that take a phone device identifier parameter are the early initialization functions such as TSPI_phoneGetDevCaps, TSPI_phoneNegotiateTSPIVersion, TSPI_phoneNegotiateExtVersion, and TSPI_phoneOpen. All other functions take phone handles.

Given a phone handle, the phone's device identifier can be retrieved with the TSPI_phoneGetID function.

The tapi32.dll client application can obtain device identifiers for various Win32 device classes associated with an opened phone by invoking TSPI_phoneGetID with the TAPI phoneGetID function. This function takes a phone handle and a device class description. It returns the device identifier for the device of the given device class that is associated with the open phone device. If the device class is tapi/phone, the device identifier of the phone device is returned. If the device class is mci/wave, the device identifier of an mci wave audio device (if supported) is returned that allows the manipulation (such as recording or playback) of audio over the phone.

To subsequently open a phone device for audio playback using the waveform API, an application calls the waveOutOpen function. The implementation of the waveOutOpen call is device specific, and each implementation has a number of options for implementing this function. If the phone's handset is on hook when invoking the function, for example, the waveOutOpen driver may return an error code message to the application that is further mapped in a request (dialog box) to the user to "pick up the phone." This is similar to requesting a CD to play back audio when no compact disc is in the player, and the existing definition of the waveform APIs can deal with it.

In contrast with line devices, for which the basic line services provide the equivalent of POTS, no minimum guaranteed set of functions is defined for phone devices. While each phone device provides at least the functions and messages listed in this section, these operations only provide a way for the software to refer to the phone; they do not offer any true operations on the physical phone device.


Supplementary Phone Services

Supplementary phone services are a set of advanced services beyond basic phone services, supported by phone devices. Typically, this set includes the following device features: hookswitch, display, distinctive ring, buttons, distinctive lamps, data area, and the ability to check call status.


Hookswitch Devices

A phone device can have multiple hookswitch devices. Each hookswitch device has a speaker and a microphone component, and operates in one of four hookswitch modes:

Onhook | The hookswitch device is onhook, and both its microphone and speaker are disabled.
Microphone only | The hookswitch device is offhook, its microphone is enabled, and its speaker is mute.
Speaker only | The hookswitch device is offhook, its microphone is disabled, and its speaker is enabled.
Microphone and speaker | The hookswitch device is offhook, and both the microphone and the speaker are enabled.

The tapi32.dll can set and query the hookswitch mode of an opened phone's hookswitch devices. To mute or unmute the microphone or speaker component of a hookswitch device, the TSPI_phoneSetHookSwitch function is used with the appropriate hookswitch mode. This function sets the hookswitch mode of one or more of the hookswitch devices of an open phone device. The TSPI_phoneGetHookSwitch function queries the hookswitch mode of a hookswitch device of an open phone device.

When the mode of a phone's hookswitch device is changed manually, for example by lifting the handset from its cradle, the service provider must send a PHONE_STATUS message to the The tapi32.dll callback function to notify it about the state change. Parameters to this message provide an indication of the change.

The volume of the speaker component of a hookswitch device can be set with TSPI_phoneSetVolume. The volume setting is different from mute in that muting a speaker and later unmuting it preserves the volume setting of the speaker. The TSPI_phoneGetVolume function returns the volume setting of the hookswitch device's speaker of an open phone device.

The microphone component of a hookswitch device can be gain controlled. The gain setting is different from mute in that muting a microphone and later unmuting it preserves the gain setting of the microphone. TSPI_phoneSetGain sets the gain of a hookswitch device's microphone of an open phone device, and TSPI_phoneGetGain returns the gain setting of the hookswitch device's microphone of an opened phone.

When the volume or gain of a phone's hookswitch device is changed, the service provider sends a PHONE_STATUS message to the tapi32.dll callback function to notify tapi32.dll about the state change. Parameters to this message provide an indication of the change.


Display

TSPI provides access to a phone's display. The display is modeled as an alphanumeric area with rows and columns. A phone's device capabilities indicate the size of a phone's display as number of rows and number of columns. Both these numbers are zero if the phone device does not have a display. The TSPI_phoneSetDisplay function writes information to the display of an open phone device. TSPI_phoneGetDisplay returns the current contents of a phone's display.

When the display of a phone device is changed, the service provider sends a PHONE_STATUS message to the tapi32.dll callback function to notify it about the state change. Parameters to this message provide an indication of the change.


Ring

A single phone may be able to ring with different ring modes. Given the wide variety of ring modes available, ring modes are identified by their ring mode number. A ring mode number ranges from zero to the number of available ring modes, with ring mode 0 indicating silence.

TSPI_phoneSetRing rings an open phone device according to a given ring mode. TSPI_phoneGetRing returns the current ring mode of an opened phone device.

When the ring mode of a phone device is changed, the service provider sends a PHONE_STATUS message to tthe tapi32.dll callback function to notify it about the state change. Parameters to this message provide an indication of the change.


Buttons

Win32 Telephony models a phone's buttons and lamps as button-lamp pairs. A button with no lamp next to it, or a lamp with no button is specified using a dummy indicator for the missing lamp or button. A button with multiple lamps is modeled by using multiple button-lamp pairs.

Information associated with a phone button can be set and retrieved. When a button is pressed, the service provider sends a PHONE_BUTTON message to the tapi32.dll callback function. Parameters of this message are a handle to the phone device and the button/lamp identifier of the button that was pressed. The keypad button '0' through '9', '*', and '#' are assigned fixed button/lamp identifiers 0 through 11.

The function TSPI_phoneSetButtonInfo sets the information associated with a button on a phone device. TSPI_phoneGetButtonInfo returns information associated with a button on a phone device. The service provider sends a PHONE_BUTTON message to the tapi32.dll callback function when a button on the phone is pressed.

The information associated with a button does not carry any semantic meaning as far as TSPI is concerned. It is useful for device-specific applications that interpret this information for a given phone device, or for display to the user, such as in an application's help system.


Lamps

The lamps on a phone device can be lit in a variety of different lighting modes. Unlike ringing patterns, lamp modes are more uniform across phone sets of different vendors. A common set of lamp modes is defined by Win32 Telephony. A lamp identified by its lamp/button identifier can be lit in a given lamp mode. A lamp can also be queried for its current lamp mode.

The lamp functions are TSPI_phoneSetLamp, which lights a lamp on a specified open phone device in a given lamp lighting mode, and TSPI_phoneGetLamp, which returns the current lamp mode of the specified lamp.

When a lamp mode of a phone device is changed, the service provider sends a PHONE_STATUS message to the tapi32.dll callback function to notify it about the state change. Parameters to this message provide an indication of the change.


Data Areas

Some phone sets support the capability of downloading data from or uploading data to the phone device, which allows the phone set to be programmed in a variety of ways. Win32 Telephony models these phone sets as having one or more download or upload areas. Each area is identified by a number that ranges from zero to the number of data areas available on the phone minus one. Sizes of each area can vary. The format of the data itself is device specific.

The TSPI_phoneSetData function downloads a buffer of data to a given data area in the phone device. TSPI_phoneGetData uploads the contents of a given data area in the phone device to a buffer.

When a data area of a phone device is changed, the service provider sends a PHONE_STATUS message to the tapi32.dll callback function to notify it about the state change. Parameters to this message provide an indication of the change.


Status

Most of the Get and Set operations described in the topics in this section deal with only one component of information. The operation TSPI_phoneGetStatus allows tapi32.dll to obtain complete status information about a phone device.

Whenever a status item changes on the phone device, the service provider sends a PHONE_STATUS message to the tapi32.dll callback function. The message parameters include a handle to the phone device and an indication of the status item that changed. tapi32.dll can use TSPI_phoneSetStatusMessages to select status changes for which it wants to be notified in the callback message. In contrast TAPI, there is no corresponding TSPI_phoneGetStatusMessages function. The tapi32.dll tracks which applications have enabled which status messages.


Extended Phone Services

The Extended Phone Services (or device-specific phone services) include all extensions to TSPI defined by the service-provider. TSPI defines a mechanism that enables service-provider vendors to extend TSPI using device-specific extensions. TSPI only defines the extension mechanism, and by doing so provides access to device-specific extensions, whose behavior is completely defined by the service provider.

TSPI consists of scalar and bit flag data constant definitions, data structures, functions, and callback messages. Procedures are defined that enable a vendor to extend most of these, as described in the topics in this section.


Scalar Data Constants

For extensible scalar data constants, a service-provider vendor can define new values in a specified range. As most data constants are DWORDs, typically the range 0x00000000 through 0x7FFFFFFF is reserved for common future extensions, while 0x80000000 through 0xFFFFFFFF are available for vendor-specific extensions. The assumption is that a vendor can define values that are natural extensions of the datatypes defined by TSPI.


Bit-Flag Data Constants

For extensible bit flag data constants, a service-provider vendor can define new values for specified bits. As most bit flag constants are DWORDs, typically a specific number of the lower bits are reserved for common extensions while the remaining upper bits are available for vendor-specific extensions. Common bit flags are assigned from bit zero up, and vendor-specific extensions should be assigned from bit 31 down. This provides maximum flexibility in assigning bit positions to common extensions versus vendor-specific extensions. A vendor is expected to define new values that are natural extensions of the bit flags defined by TSPI.

Extensible data structures have a variably sized field that is reserved for device-specific use. Being variably sized, the service provider decides the amount of information and the interpretation. A vendor that defines a device-specific member is expected to make these natural extensions of the original data structure defined by TSPI.


Functions and Messages

The TSPI_phoneDevSpecific function and associated PHONE_DEVSPECIFIC message enable the tapi32.dll client application to access device-specific phone features that are unavailable through the common telephony services on phones. The parameter profile of the TSPI_phoneDevSpecific function is generic in that little interpretation of the parameters is made by TSPI. Device-handle parameters have TSPI-defined meanings and are translated appropriately between the application and the service provider. Generic parameters are simply passed through unmodified. The interpretation of the generic parameters is defined by the service provider and must be understood by any applications that use them. An application that relies on device-specific extensions will not generally work with other service providers. However, applications written entirely to the common telephony phone services will work with the extended service provider.

Regarding handle translation, the passthrough nature of the generic parts of device-specific extensions has an imporant consequence. A service provider has no way to relate the handles used at the TSPI level to those at the TAPI level except by passing them through the predefined handle parameters and fields. Any handle put into the generic extension area is untranslated by tapi32.dll as it is passed between application and service provider. The designer of a service-provider extension should generally not define extensions that pass handles in this way.

The appropriate approach to define a device-specific extension that needs to refer to specific devices without using handles is to refer to them using their absolute device identification. The device identifier used in opening a phone at the TAPI level, for example, is strictly the same value that is used at the TSPI level to open the phone.

This is the motivation for the dwPhoneDeviceIDBase parameter in the TSPI_providerInit function. It adjusts the service provider's device identifier numbering to be the same as the numbering used at the TAPI level. This gives the service-provider designer the flexibility to use device identifiers to identify devices in device-specific extensions.

There is no central registry for manufacturer identifiers. Instead a unique identifier generator, called extidgen.exe, is made available as part of TSPI. The vendor that designs a set of device-specific extensions uses this utility to obtain a unique identifier for those extensions. This unique identifier must be published as part of the specification of the extensions to allow application developers to access the extensions.


Asynchronous Phone Operations

There are nine asynchronous operations related to phones. These are initiated by the TSPI_phoneDevSpecific, TSPI_phoneSetButtonInfo, TSPI_phoneSetData, TSPI_phoneSetDisplay, TSPI_phoneSetGain, TSPI_phoneSetHookSwitch, TSPI_phoneSetLamp, TSPI_phoneSetRing, and TSPI_phoneSetVolume functions. If an application calls the TAPI phoneClose function and has the only handle to the phone, TAPI calls the TSPI_phoneClose function to direct the service provider to terminate the asynchronous operations and call the ASYNC_COMPLETION callback function as appropriate. If the application does not have the only handle to the phone, the service provider receives no notification of the request and any outstanding asynchronous operations remain active.


TSPI Functions

This section contains an alphabetic list of the service provider, line device, phone device, and callback functions in the Telephony Service Provider Interface (TSPI) and the Telephony User Interface Service Provider Interface (TUISPI).


TSPI Service Provider Functions

Following are the TSPI service provider functions and their descriptions.


TSPI_providerConfig

The TSPI_providerConfig function is obsolete. TAPI version 1.4 or earlier service providers can implement this TSPI function. TAPI version 2.0 or later TSPs implement TUISPI_providerConfig.

The TSPI_providerConfig function gathers configuration information from the user. It may use a dialog box, and this dialog box can include sub-dialog boxes associated with other APIs (such as Comm/datamodem) for the setup of specific devices.

LONG TSPI_providerConfig(
  HWND hwndOwner,
  DWORD dwPermanentProviderID
);

Parameters

hwndOwner
The handle of the parent window in which the function can create any dialog box windows required during the configuration.
dwPermanentProviderID
The service provider's permanent provider identifier.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_OPERATIONFAILED, LINEERR_NOMEM.

Remarks

This function may be called while the service provider is in use (that is, between calls of TSPI_providerInit and TSPI_providerShutdown).

Any changes that affect the behavior visible through TSPI should take effect only when the service provider is restarted at the next TSPI_providerInit.

The Telephony Control Panel utility supplied with Windows Telephony in versions 1.4 and earlier calls this function when the setup command is invoked.

There is no directly corresponding function at the TAPI level. In TAPI, applications have access to the functions lineConfigDialog and phoneConfigDialog, which allow configuration of parameters of a particular line or phone once it has been installed.

See Also

TSPI_lineConfigDialog, TSPI_phoneConfigDialog, TSPI_providerInstall, TSPI_providerRemove, TUISPI_providerConfig


TSPI_providerCreateLineDevice

The TSPI_providerCreateLineDevice function is called by TAPI in response to receipt of a LINE_CREATE message from the service provider, which allows the dynamic creation of a new line device.

LONG TSPIAPI TSPI_providerCreateLineDevice(
  DWORD dwTempID,
  DWORD dwDeviceID
);

Parameters

dwTempID
The temporary device identifier that the service provider passed to TAPI in the LINE_CREATE message.
dwDeviceID
The device identifier that TAPI assigns to this device if this function succeeds.

Return Values

Returns zero if the request succeeds or an error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_OPERATIONFAILED.

Remarks

When TAPI receives a LINE_CREATE message from a service provider, it calls this function (it never calls this function spontaneously). TAPI adds 1 to the number of devices of that type, and passes the resulting new, unused device identifier as the dwDeviceID parameter to this function. It also passes in the function the dwParam2 parameter from the LINE_CREATE message as dwTempID.

Note Adding the new device to the end of the device list is likely to produce noncontiguous device identifiers for the service provider; service providers that support dynamic device creation must also support noncontiguous device identifiers.

If the service provider recognizes the dwTempID and succeeds in setting up the structures and such that it needs to support the new device, it saves off the dwDeviceID, and returns SUCCESS. If this function is unsuccessful, TAPI doesn't add the device, and there are no negative effects (the LINE_CREATE message is ignored). If this function completes successfully, TAPI then informs applications of the availability of the new device using LINE_CREATE or LINE_LINEDEVSTATE (LINEDEVSTATE_REINIT) messages.

Older service providers that do not export this function, however, also should not send LINE_CREATE messages, which means TAPI would not try to call this function.

See Also

LINE_CREATE, LINE_LINEDEVSTATE


TSPI_providerCreatePhoneDevice

The TSPI_providerCreatePhoneDevice function is called by TAPI in response to receipt of a PHONE_CREATE message from the service provider, which allows the dynamic creation of a new phone device.

LONG TSPIAPI TSPI_providerCreatePhoneDevice(
  DWORD dwTempID,
  DWORD dwDeviceID
);

Parameters

dwTempID
The temporary device identifier that the service provider passed to TAPI in the PHONE_CREATE message.
dwDeviceID
The device identifier that TAPI assigns to this device if this function succeeds.

Return Values

Returns zero if the request succeeds or an error number if an error occurs. Possible return values are:

LINEERR_BADDEVICEID, LINEERR_NOMEM, LINEERR_OPERATIONFAILED.

Remarks

When TAPI receives a PHONE_CREATE message from a service provider, it calls this function (it never calls this function spontaneously). TAPI adds 1 to the number of devices of that type, and passes the resulting new, unused device identifier as the dwDeviceID parameter to this function. It also passes in the function the dwParam2 parameter from the PHONE_CREATE message as dwTempID. Adding the new device to the end of the device list is likely to produce noncontiguous device identifiers for the service provider; service providers that support dynamic device creation must also support noncontiguous device identifiers.

If the service provider recognizes the dwTempID parameter and succeeds in setting up the structures and such that it needs to support the new device, it saves off the dwDeviceID, and returns SUCCESS. If this function is unsuccessful, TAPI doesn't add the device, and there are no negative effects (the PHONE_CREATE message is ignored). If this function completes successfully, TAPI informs applications of the availability of the new device using PHONE_CREATE or PHONE_STATE (PHONESTATE_REINIT) messages.

Older service providers that do not export this function, however, also should not send PHONE_CREATE messages, which means TAPI would not try to call this function.

See Also

PHONE_CREATE, PHONE_STATE


TSPI_providerEnumDevices

TAPI calls the TSPI_providerEnumDevices function before TSPI_providerInit to determine the number of line and phone devices supported by the service provider.

LONG TSPIAPI TSPI_providerEnumDevices(
  DWORD dwPermanentProviderID,
  LPDWORD lpdwNumLines,
  LPDWORD lpdwNumPhones,
  HPROVIDER hProvider,
  LINEEVENT lpfnLineCreateProc,
  PHONEEVENT lpfnPhoneCreateProc
);

Parameters

dwPermanentProviderID
The permanent identifier, unique within the service providers on this system, of the service provider being initialized.
lpdwNumLines
A pointer to a DWORD-sized memory location into which the service provider must write the number of line devices it is configured to support. TAPI initializes the value to 0, so if the service provider fails to write a different value, the value 0 is assumed.
lpdwNumPhones
A pointer to a DWORD-sized memory location into which the service provider must write the number of phone devices it is configured to support. TAPI initializes the value to 0, so if the service provider fails to write a different value, the value 0 is assumed.
hProvider
An opaque DWORD-sized value that uniquely identifies this instance of this service provider during this execution of the Win32 Telephony environment.
lpfnLineCreateProc
A pointer to the LINEEVENT callback procedure supplied by TAPI. The service provider uses this function to send LINE_CREATE messages when a new line device needs to be created. This function should not be called to send a LINE_CREATE message until after the service provider has returned from the TSPI_providerInit procedure.
lpfnPhoneCreateProc
A pointer to the PHONEEVENT callback procedure supplied by TAPI. The service provider uses this function to send PHONE_CREATE messages when a new phone device needs to be created. This function should not be called to send a PHONE_CREATE message until after the service provider has returned from the TSPI_providerInit procedure.

Return Values

Returns zero if the request succeeds or an error number if an error occurs. Possible return values are:

LINEERR_NOMEM, LINEERR_OPERATIONFAILED.

Remarks

In previous versions of TAPI, implementation of this function was optional. Beginning with TAPI 2.0, implementation of this function is mandatory in all service providers. TAPI no longer checks telephon.ini or the Registry at TAPI startup to determine the initial number of lines and phones supported by a service provider.

See Also

LINE_CREATE, LINEEVENT, PHONE_CREATE, PHONEEVENT, TSPI_providerInit


TSPI_providerInit

The TSPI_providerInit function initializes the service provider and gives it parameters required for subsequent operation.

LONG TSPI_providerInit(
  DWORD dwTSPIVersion,
  DWORD dwPermanentProviderID,
  DWORD dwLineDeviceIDBase,
  DWORD dwPhoneDeviceIDBase,
  DWORD dwNumLines,
  DWORD dwNumPhones,
  ASYNC_COMPLETION lpfnCompletionProc,
  LPDWORD lpdwTSPIOptions
);

Parameters

dwTSPIVersion
The version of the TSPI definition under which this function must operate. The caller can use TSPI_lineNegotiateTSPIVersion with the special dwDeviceID INITIALIZE_NEGOTIATION to negotiate a version that is guaranteed to be acceptible to the service provider.
dwPermanentProviderID
The permanent identifier, unique within the service providers on this system, of the service provider being initialized.
dwLineDeviceIDBase
The lowest device identifier for the line devices supported by this service provider.
dwPhoneDeviceIDBase
The lowest device identifier for the phone devices supported by this service provider.
dwNumLines
The number of line devices this service provider supports. The value returned is the number of line devices reported in TSPI_providerEnumDevices.
dwNumPhones
The number of phone devices this service provider supports. The value returned is the number of phone devices reported in TSPI_providerEnumDevices.
lpfnCompletionProc
The procedure the service provider calls to report completion of all asynchronously operating procedures on line and phone devices.
lpdwTSPIOptions
A pointer to a DWORD-sized memory location, into which the service provider can write a value specifying LINETSPIOPTIONS_ values. This parameter allows the service provider to return bits indicating optional behaviors desired of TAPI. TAPI sets the options DWORD to 0 before calling TSPI_providerInit, so if the service provider doesn't want any of these options, it can just leave the DWORD set to 0.

At this time, only one bit is defined to be returned through this pointer: LINETSPIOPTION_NONREENTRANT. The service provider sets this bit if it is not designed for fully pre-emptive, multithreaded, multitasking, multiprocessor operation (for example, updating of global data protected by mutexes). When this bit is set, TAPI only makes one call at a time to the service provider; it does not call any other entry point, nor that entry point again, until the service provider returns from the original function call. Without this bit set, TAPI may call into multiple service provider entry points, including multiple times to the same entry point, simultaneously (actually simultaneously in a multiprocessor system).

Important Note It must be emphasized that setting this bit degrades performance. It is strongly recommended that this be used only for development but not a shipped production service provider.

TAPI does not serialize access to TSPI functions that display a dialog box (TUISPI_lineConfigDialog, TUISPI_lineConfigDialogEdit, TUISPI_phoneConfigDialog, TUISPI_providerConfig, TUISPI_providerInstall, TUISPI_providerRemove) so that they do not block other TSPI functions from being called; the service provider must include internal protection on these functions.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_INIFILECORRUPT, LINEERR_NOMULTIPLEINSTANCE.

Remarks

This function is guaranteed to be called before any of the other functions prefixed with TSPI_line or TSPI_phone except TSPI_lineNegotiateTSPIVersion. It is strictly paired with a subsequent call to TSPI_providerShutdown These pairs may overlap, for example, when the Telephony Control Panel utility supplied with Windows Telephony in versions 1.4 and earlier is used while telephony operations are in progress. The call to this function must be ignored (returning success) if there is already an outstanding pair.

A service provider should perform as many consistency checks as is practical at the time. TSPI_providerInit is called to ensure that it is ready to run. Some consistency or installation errors, however, cannot be detected until the operation is attempted. The error LINEERR_NODRIVER can be used to report such nonspecific errors at the time they are detected.

There is no directly corresponding function at the TAPI level. At that level, multiple different usage instances can be outstanding, with an "application handle" returned to identify the instance in subsequent operations. At TSPI level, the interface architecture supports only a single usage instance for each distinct service provider.

See Also

TSPI_lineNegotiateTSPIVersion, TSPI_providerShutdown, TUISPI_lineConfigDialog, TUISPI_lineConfigDialogEdit, TUISPI_phoneConfigDialog, TUISPI_providerConfig, TUISPI_providerInstall, TUISPI_providerRemove


TSPI_providerInstall

The TSPI_providerInstall function is obsolete. TAPI version 1.4 or earlier service providers can implement this TSPI function. TAPI version 2.0 or later TSPs implement TUISPI_providerInstall.

The TSPI_providerInstall function installs any additional "pieces" of the provider into the right directories (or at least verifying that they're there), sets up the provider's registry entries for its lines and phones, and creates any other entries necessary for the service provider. It is called from the Telephony Control Panel utility (supplied with Windows Telephony in versions 1.4 and earlier) when the Add button is pressed.

LONG TSPI_providerInstall(
  HWND hwndOwner,
  DWORD dwPermanentProviderID
);

Parameters

hwndOwner
The handle of the parent window in which the function can create any dialog box windows that are required during installation.
dwPermanentProviderID
The service provider's permanent provider identifier.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_NOMEM. LINEERR_INVALPARAM.

Remarks

This function completes the installation of other pieces required by the service provider after its entries in the [Providers] section in the registry have been made. If the service provider requires any additional privately-defined entries in the registry for proper operation, they must also be installed. A typical way to install this section with its entries is to call TSPI_providerConfig.

This function must leave the system in a consistent state. It should run to completion, not allowing the user to abort the installation when it is partly completed. If installation fails, it is the provider's responsibility to "back out" what was done and return an error. This may imply pre-scanning to verify that a complete installation is possible, before the installation begins.

This function is called only once, during installation of the service provider, until there is a call to TSPI_providerRemove. It must be called before any other TSPI-defined function.

The Telephony Control Panel utility supplied with Windows Telephony in versions 1.4 and earlier calls this function (with external sequence requirements met as described here) when the "add" command is invoked. It does not call TSPI_providerConfig for the "add" command.

There is no corresponding function at the TAPI level. At that level, applications expect to have service providers already installed. Running applications are informed about dynamic reconfiguration through the LINEDEVSTATE_REINIT or PHONESTATE_REINIT value in the LINE_LINEDEVSTATE or PHONE_STATE message.

See Also

LINE_LINEDEVSTATE, PHONE_STATE, TSPI_providerConfig, TSPI_providerInit, TSPI_providerRemove, TSPI_providerShutdown


TSPI_providerRemove

The TSPI_providerRemove function is obsolete. TAPI version 1.4 or earlier service providers can implement this TSPI function. TAPI version 2.0 or later TSPs implement TUISPI_providerRemove.

The TSPI_providerRemove function asks the user to confirm elimination of the service provider. It is the responsibility of the service provider to remove any registry entries that the service provider added at addProvider time, as well as any other modules and files that are no longer needed.

LONG TSPI_providerRemove(
  HWND hwndOwner,
  DWORD dwPermanentProviderID
);

Parameters

hwndOwner
The handle of the parent window in which the function can create any dialog box windows required during the removal.
dwPermanentProviderID
The service provider's permanent provider identifier.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM.

Remarks

This function must guarantee that the service provider's section and privately-defined information for the service provider is removed from the registry if it returns success. In particular, the [Provider<PPID>] section whose <PPID> matches dwPermanentProviderID must be removed, including its NumLines and NumPhones entries. If the function returns success, it is the caller's responsibility to remove the matching ProviderIDx and ProviderFilenamex entries from the [Providers] section, and renumber the remaining entries in the [Providers] section accordingly.

This procedure must leave the system in a consistent state. It should run to completion, not allowing the user to abort the removal when it is partly completed. If removal fails, it is the provider's responsibility to "back out" what was done and return an error. This may imply pre-scanning to verify that a complete removal is possible, before the removal begins.

This function can be called while the service provider is in use (that is, between TSPI_providerInit and TSPI_providerShutdown). If this happens, the service provider should do an appropriate combination of displaying a user dialog box to announce any conflict and confirm removal, restricting removal options to those that can be performed transparently, or issuing LINE_CLOSE and PHONE_CLOSE messages to inform TAPI and applications that the affected devices have been forcibly closed for removal. In any case, any changes that affect the behavior visible through TSPI should take effect only when the service provider is shut down at the next TSPI_providerShutdown.

This function should not return LINEERR_INUSE or other errors that might occur because the provider is in use by an application; instead, the provider should confer with the user directly about this problem, and then return LINEERR_OPERATIONFAILED if the user decides to abort the operation.

This procedure is called only once, at the time of removal of the service provider, until there is a call to TSPI_providerInstall. It is the responsibility of the caller to ensure this.

The Telephony Control Panel utility supplied with Windows Telephony in versions 1.4 and earlier calls this function (with external sequence requirements met as described here) when the "remove" command is invoked.

There is no corresponding function at the TAPI level. At that level, applications expect to have service providers already installed; otherwise their lines and phones do not appear within the available sequence of device identifiers. Running applications are informed about dynamic reconfiguration, including removal of service providers, through the LINEDEVSTATE_REINIT or PHONESTATE_REINIT value in the LINE_LINEDEVSTATE or PHONE_STATE message.

See Also

LINE_CLOSE, LINE_LINEDEVSTATE, PHONE_CLOSE, PHONE_STATE, TSPI_providerInit, TSPI_providerInstall, TSPI_providerShutdown


TSPI_providerShutdown

The TSPI_providerShutdown function shuts down the service provider. The service provider terminates any activities it has in progress and releases any resources it has allocated.

LONG TSPI_providerShutdown(
  DWORD dwTSPIVersion,
  DWORD dwPermanentProviderID
);

Parameters

dwTSPIVersion
The version of the TSPI definition under which this function must operate. The caller can use TSPI_lineNegotiateTSPIVersion or TSPI_phoneNegotiateTSPIVersion with the special dwDeviceID INITIALIZE_NEGOTIATION to negotiate a version that is guaranteed to be acceptible to the service provider.
dwPermanentProviderID
This parameter allows the service provider to determine which among multiple possible instances of the service provider is being shut down. The value of the parameter is identical to that passed in the parameter of the same name in TSPI_providerInit.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM.

Remarks

The final paired call to this function must be the last call to any of the TSPI functions prefixed with TSPI_line or TSPI_phone other than TSPI_lineNegotiateTSPIVersion, or TSPI_phoneNegotiateTSPIVersion. It is the caller's responsibility to ensure this.

This function should always succeed except in extraordinary circumstances. Most callers will probably ignore the return code because they will be unable to compensate for any error that occurs. The specified return values are more advisory for development diagnostic purposes than anything else.

There is no directly corresponding function in TAPI. In TAPI, multiple different usage instances can be outstanding, with an "application handle" parameter to identify the instance to be operated on. In TSPI, the interface architecture supports only a single usage instance for each distinct service provider.

See Also

TSPI_lineNegotiateTSPIVersion, TSPI_phoneNegotiateTSPIVersion, TSPI_providerInit


TSPI Line Device Functions

This section contains an alphabetic list of the available line device functions in the Telephony SPI. The information for each function includes the following:

  • A statement of the function's purpose.
  • The correct syntax for the function.
  • A description of the function's parameters, including valid call states.
  • A description of the function's return value.
  • A Remarks section that can include any or all of the following: a list of the valid call states on entry of the function and typical call state transitions when the request completes; a description of which members of large data structures must be filled in by the service provider and which members must have their values preserved intact; and comparison with a corresponding function within TAPI.
  • References to other functions, messages, or data structures.

    Note The actual states in which a function can be performed may be limited by the capabilities of the service provider. Service providers must set the dwCallFeatures member in the LINECALLSTATUS structure, the dwAddressFeatures member in the LINEADDRESSSTATUS structure, and the dwLineFeatures member in the LINEDEVSTATUS structure to indicate to applications whether or not a function is permitted at that point in time.


TSPI_lineAccept

The TSPI_lineAccept function accepts the specified offered call. It can optionally send the specified user-user information to the calling party.

LONG TSPI_lineAccept(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPCWSTR lpsUserUserInfo,
  DWORD dwSize
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the call to be accepted. The call state of hdCall can be offering.
lpsUserUserInfo
A pointer to a string containing user-user information to be sent to the remote party as part of the call accept. This pointer is NULL if no user-user information is to be sent. User-user information is only sent if supported by the underlying network (see LINEDEVCAPS).
dwSize
The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, dwSize is ignored.

Return Values

Returns dwRequestID if the function is completed asynchronously or an error number if an error occurs. The lResult parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_USERUSERINFOTOOBIG, LINEERR_OPERATIONUNAVAIL.

Remarks

The TSPI_lineAccept function is used in telephony environments (such as ISDN) that allow alerting associated with incoming calls to be separate from the initial offering of the call. When a call comes in, the call is first offered. For some small time duration, the client application may have the option to reject the call using TSPI_lineDrop, redirect the call to another station using TSPI_lineRedirect, answer the call using TSPI_lineAnswer, or accept the call using TSPI_lineAccept. After a call has been successfully accepted, alerting at both the called and calling device begins, and typically the call state transitions to the accepted state. The service provider must set the flag LINEADDRCAPFLAGS_ACCEPTTOALERT in the dwAddrCapFlags member of the LINEADDRESSCAPS data structure if the application must call TSPI_lineAccept for alerting to begin.

To TAPI, alerting is reported using the LINE_LINEDEVSTATE message with the ringing indication.

TSPI_lineAccept may also be supported by non-ISDN service providers. The call state transition to the accepted state can be used by other of the TAPI clients as an indication that some application has claimed responsibility for the call and has presented the call to the user.

The client application has the option to send user-user information at the time of the accept. Even if user-user information can be sent, often no guarantees are made that the network will deliver this information to the calling party. The client application may consult a line's device capabilities to determine whether call accept is available.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINE_LINEDEVSTATE, LINEADDRESSCAPS, LINEDEVCAPS, TSPI_lineAnswer, TSPI_lineDrop, TSPI_lineOpen, TSPI_lineRedirect


TSPI_lineAddToConference

The TSPI_lineAddToConference function adds the call specified by hdConsultCall to the conference call specified by hdConfCall.

LONG TSPI_lineAddToConference(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdConfCall,
  HDRVCALL hdConsultCall
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdConfCall
The handle to the conference call. The call state of hdConfCall can be onHoldPendingConference or onHold.
hdConsultCall
The handle to the call to be added to the conference call. This call cannot be either a parent of another conference or a participant in any conference. Depending on the device capabilities indicated in LINEADDRESSCAPS, the hdConsultCall parameter may not necessarily have been established using TSPI_lineSetupConference or TSPI_linePrepareAddToConference. The call state of hdConsultCall can be connected, onHold, proceeding, or ringback.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_CONFERENCEFULL, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM.

Remarks

The servicer provider returns LINEERR_INVALCALLHANDLE if hdConsultCall is a parent of another conference or already a participant in a conference, or hdConsultCall cannot be added for other reasons, such as it must have been established using TSPI_lineSetupConference or TSPI_linePrepareAddToConference.

Note The call handle of the added party remains valid after adding the call to a conference; typically, its state changes to conferenced while the state of the conference call becomes connected. The handle to an individual participating call can be used later to remove that party from the conference call using TSPI_lineRemoveFromConference.

The call states of the calls participating in a conference are not independent. For example, when dropping a conference call, all participating calls can automatically become idle. TAPI can consult the line's device capabilities to determine what form of conference removal is available. TAPI or its client applications should track the LINE_CALLSTATE messages to determine what happened to the calls involved.

The conference call is established either through TSPI_lineSetupConference or TSPI_lineCompleteTransfer. Typically, the call added to a conference is established using TSPI_lineSetupConference or TSPI_linePrepareAddToConference. Some switches may allow adding of an arbitrary call to conference, and such a call may have been set up using TSPI_lineMakeCall and be on (hard) hold. All calls that are part of a conference must exist on the same open line.

Any monitoring (media, tones, digits) on a conference call applies only to the hdConfCall parameter, not to the individual participating calls.

This function has no restrictions based on privilege as in the corresponding function at the TAPI level. There is no explicit requirement for the service provider to track the relationships between the "parent" conference call and its participants, because there is no TSPI correspondence to the TAPI function lineGetCalls. Many service providers may find it necessary to track these relationships internally to implement the other conference call management functions.

See Also

LINE_CALLSTATE, TSPI_lineCompleteTransfer, TSPI_linePrepareAddToConference, TSPI_lineRemoveFromConference, TSPI_lineSetupConference


TSPI_lineAnswer

The TSPI_lineAnswer function answers the specified offering call.

LONG TSPI_lineAnswer(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPCSTR lpsUserUserInfo,
  DWORD dwSize
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The service provider's handle to the call to be answered. The call state of hdCall can be offering or accepted.
lpsUserUserInfo
A pointer to a string containing user-user information to be sent to the remote party at the time of answering the call. If this pointer is NULL, it indicates that no user-user information is to be sent. User-user information is only sent if supported by the underlying network (as indicated in LINEDEVCAPS).
dwSize
The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, dwSize is ignored.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INUSE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_USERUSERINFOTOOBIG.

Remarks

When a new call arrives, the service provider sends TAPI a LINE_NEWCALL message to exchange handles for the call. The service provider follows this with a LINE_CALLSTATE message to inform TAPI and its client applications of the call's state. A client application typically answers the call using TSPI_lineAnswer. Typically, after the call is successfully answered, the call transitions to the connected state.

In some telephony environments (like ISDN) where user alerting is separate from call offering, TAPI and its client applications may have the option to first accept a call prior to answering, or instead to reject or redirect the offering call.

If a call is offered at the time another call is already active, the new call is connected to by invoking TSPI_lineAnswer. The effect this has on the existing active call depends on the line's device capabilities. The first call may be unaffected, it may automatically be dropped, or it may automatically be placed on hold. The appropriate LINE_CALLSTATE messages are used to report state transitions to TAPI about both calls.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINE_NEWCALL, LINEDEVCAPS


TSPI_lineBlindTransfer

The TSPI_lineBlindTransfer function performs a blind or single-step transfer of the specified call to the specified destination address.

LONG TSPI_lineBlindTransfer(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPCWSTR lpszDestAddress,
  DWORD dwCountryCode
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The service provider's handle to the call to be transferred. The call state of hdCall can be connected.
lpszDestAddress
A pointer to a NULL-terminated string identifying where the call is to be transferred to. The destination address uses the standard dialable number format.
dwCountryCode
The country code of the destination. This should be used by the implementation to select the call progress protocols for the destination address. If a value of 0 is specified, the service provider should use a default. dwCountryCode is not validated by TAPI when this function is called.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_ADDRESSBLOCKED, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCOUNTRYCODE.

Remarks

The service provider carries out no dialing if it returns LINEERR_INVALADDRESS.

Blind transfer differs from a consultation transfer in that no consultation call is made visible to TAPI. Typically, after the blind transfer successfully completes, the specified call is cleared from the line it was on and transitions to the idle state. The service provider's call handle must remain valid after the transfer has completed. TAPI causes this handle to be invalidated when it is no longer interested in the transferred call using TSPI_lineCloseCall.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, TSPI_lineCloseCall


TSPI_lineClose

The TSPI_lineClose function closes the specified open line device after completing or aborting all outstanding calls and asynchronous operations on the device.

LONG TSPI_lineClose(
  HDRVLINE hdLine
);

Parameters

hdLine
The service provider's handle to the line to be closed. After the line is successfully closed, this handle is no longer valid.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Remarks

The service provider must report completion for every asynchronous operation. If TSPI_lineClose is called for a line on which there are outstanding asynchronous operations, the operations are reported complete with an appropriate result or error code before this procedure returns.

A similar requirement exists for active calls on the line. Outstanding operations must be reported complete with appropriate result or error codes. Active calls can also be dropped, if required, and if this behavior was indicated by the LINEDEVCAPFLAGS_CLOSEDROP bit in the LINEDEVCAPS structure.

After this procedure returns, the service provider must report no further htCall on the line or calls that were on the line. The service provider's handles for the line and calls on the line become "invalid."

The service provider must relinquish nonsharable resources it reserves while the line is open. For example, closing a line accessed through a comm port and modem should result in closing the comm port, making it once again available for use by other applications.

The service provider does not issue the LINE_LINEDEVSTATE message in response to this function invocation because the line closes and there is no longer any interest in its state changes.

See Also

LINE_CLOSE, LINE_LINEDEVSTATE, LINEDEVCAPS


TSPI_lineCloseCall

The TSPI_ lineCloseCall function deallocates the call after completing or aborting all outstanding asynchronous operations on the call.

LONG TSPI_lineCloseCall(
  HDRVCALL hdCall
);

Parameters

hdCall
The service provider's handle to the call to be closed. After the call is successfully closed, this handle is no longer valid. The call state can be any state.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Remarks

The service provider must report completion for asynchronous operations. If TSPI_lineCloseCall is called for a call on which there are outstanding asynchronous operations, the operations should be reported complete with an appropriate result or error code before this procedure returns. After this procedure returns, the service provider must report no further events on the call. The service provider's handles for the line and calls on the line become "invalid."

TAPI does not call TSPI_lineCloseCall if a service provider synchronously returns an error from a call to the TSPI_lineMakeCall function. But TAPI does call TSPI_lineCloseCall if the service provider returns an error from the asynchronous operation initiated by TSPI_lineMakeCall.

If there is an active call on the line at the time of TSPI_lineCloseCall, the call can be dropped if this behavior is indicated by the LINEDEVCAPFLAGS_CLOSEDROP bit in the LINEDEVCAPS structure.

If the service provider can determine that there is another agent sharing control of the call, such as in a party line situation with a separate handset, the service provider simply lets control of the call pass to the other agent rather than forcibly dropping it.

This function should always succeed except in extraordinary circumstances. Most callers will probably ignore the return code because they will be unable to compensate for any error that occurs. The specified return values are more advisory for development diagnostic purposes than anything else.

This function is called when the last application with a handle to this call executes lineDeallocateCall.

See Also

LINEDEVCAPS, TSPI_lineMakeCall


TSPI_lineCompleteCall

The TSPI_lineCompleteCall function is used to specify how a call that cannot be connected normally is to be completed instead. The network or switch may not be able to complete a call because network resources are busy or the remote station is busy or doesn't answer.

LONG TSPI_lineCompleteCall(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPDWORD lpdwCompletionID,
  DWORD dwCompletionMode,
  DWORD dwMessageID
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The service provider's handle to the call whose completion is requested. The call state of hdCall can be busy, ringback, or proceeding.
lpdwCompletionID
A pointer to a DWORD-sized memory location where the service provider writes a completion identifer. This uniquely identifies a completion request in progress on the line that contains the hdCall. In particular, a completion identifier becomes invalid after the request completes or is canceled using the TSPI_lineUncompleteCall function. The service provider is free to reuse the completion identifier as soon as it becomes invalid.
dwCompletionMode
The way in which the call is to be completed. This parameter uses the following LINECALLCOMPLMODE_ constants. Only one of the indicated flags can be set at a time:
LINECALLCOMPLMODE_CAMPON
Queue the call until the call can be completed. The call remains in the busy state while queued.
LINECALLCOMPLMODE_CALLBACK
Request the called station to return the call when the called station becomes idle. The call typically transitions to the idle state.
LINECALLCOMPLMODE_INTRUDE
Request that the call be added to an existing physical call at the called station (barge in). The call typically transitions to the connected state when the intrusion occurs.
LINECALLCOMPLMODE_MESSAGE
Leave a short predefined message for the called station (Leave Word Calling). The message to be sent is specified in dwMessageID. The call typically transitions to the idle state.
dwMessageID
The message that is to be sent when completing the call using LINECALLCOMPLMODE_MESSAGE. This identifier selects the message from a small number of predefined messages. This parameter is not validated by TAPI when this function is called.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLCOMPLMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_COMPLETIONOVERRUN, LINEERR_INVALMESSAGEID.

Remarks

This function is considered complete when the request is accepted by the network or switch; not when the request is fully completed in the way specified. When the called station or network enters a state where the call can be completed as requested, the service privider must send a LINE_CALLSTATE message with the call state equal to offering. The call's LINECALLINFO record lists the reason for the call as CALLCOMPLETION and provides the completion identifier as well. It is possible to have multiple call completion requests outstanding at any given time; the maximum number is device dependent. The completion identifier is also used to refer to each individual request so requests can be canceled by calling TSPI_lineUncompleteCall.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINECALLINFO, LINECALLCOMPLMODE_ Constants, LINECALLSTATUS, TSPI_lineGetCallInfo, TSPI_lineUncompleteCall


TSPI_lineCompleteTransfer

The TSPI_lineCompleteTransfer function completes the transfer of the specified call to the party connected in the consultation call. If dwTransferMode is LINETRANSFERMODE_CONFERENCE, the original call handle is changed to a conference call. Otherwise, the service provider should send call state messages changing the calls to idle.

LONG TSPI_lineCompleteTransfer(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  HDRVCALL hdConsultCall,
  HTAPICALL htConfCall,
  LPHDRVCALL lphdConfCall,
  DWORD dwTransferMode
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The service provider's handle to the call to be transferred. The call state of hdCall can be onHoldPendingTransfer.
hdConsultCall
A handle to the call that represents a connection to the destination of the transfer. The call state of hdConsultCall can be connected, ringback, busy, or proceeding.
htConfCall
This parameter is only valid if dwTransferMode is specified as LINETRANSFERMODE_CONFERENCE. The service provider must save this parameter value and use it in all subsequent calls to the LINEEVENT procedure reporting events on the call. Otherwise this parameter is ignored.
lphdConfCall
A pointer to an HDRVCALL representing the service provider's identifier for the call. This parameter is only valid if dwTransferMode is specified as LINETRANSFERMODE_CONFERENCE. The service provider must fill this location with its handle for the new conference call before returning from this function.
dwTransferMode
Specifies how the initiated transfer request is to be resolved. This parameter uses the following LINETRANSFERMODE_ constants:
LINETRANSFERMODE_TRANSFER
Resolve the initiated transfer by transferring the initial call to the consultation call.
LINETRANSFERMODE_CONFERENCE
Resolve the initiated transfer by conferencing all three parties into a three-way conference call.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

This function completes the transfer of the original call, hdCall, to the party currently connected through hdConsultCall. The consultation call is typically dialed on the consultation call allocated as part of TSPI_lineSetupTransfer, but it can be any call to which the switch is capable of transferring hdCall.

The transfer request can be resolved either as a transfer or as a three-way conference call. When resolved as a transfer, the parties connected through hdCall and hdConsultCall are connected to each other, and both hdCall and hdConsultCall transition to the idle state.

When resolved as a conference, all three parties enter into a conference call. Both existing call handles remain valid, but transition to the conferenced state. A conference call handle is created and returned, and it transitions to the connected state.

It may also be possible to perform a blind transfer of a call using TSPI_lineBlindTransfer.

This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETION message reports success. In other words, it must not issue any LINEEVENT message for the new call or include it in call counts in messages or status data structures for the line.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINEEVENT, LINETRANSFERMODE_ Constants, TSPI_lineBlindTransfer, TSPI_lineCloseCall, TSPI_lineSetupTransfer


TSPI_lineConditionalMediaDetection

The TSPI_lineConditionalMediaDetection function is invoked by TAPI whenever a client application uses LINEMAPPER as the dwDeviceID in a lineOpen function to request that lines be scanned to find one that supports the desired media modes and call parameters. TAPI scans based on the union of the desired media mode and the other media modes currently being monitored on the line, to give the service provider the opportunity to indicate if it cannot simultaneously monitor for all of the requested media modes. If the service provider can monitor for the indicated set of media modes and support the capabilities indicated in lpCallParams, it replies with a success indication. It leaves the active media monitoring modes for the line unchanged.

LONG TSPI_lineConditionalMediaDetection(
  HDRVLINE hdLine,
  DWORD dwMediaModes,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

hdLine
The service provider's handle to the line on which media monitoring and parameter capabilities are to be set.
dwMediaModes
The media mode(s) currently of interest to the calling application. This parameter uses the following LINEMEDIAMODE_ constants:
LINEMEDIAMODE_UNKNOWN
Unclassified calls.
LINEMEDIAMODE_INTERACTIVEVOICE
Interactive voice media type (manages live voice calls).
LINEMEDIAMODE_AUTOMATEDVOICE
Voice data managed by an automated application. In cases where the service provider does not distinguish between automated or interactive voice, this should be treated the same as interactive voice.
LINEMEDIAMODE_DATAMODEM
Calls with the data modem media mode.
LINEMEDIAMODE_G3FAX
Calls of the group 3 fax media type.
LINEMEDIAMODE_TDD
Calls with the TDD (Telephony Devices for the Deaf) media mode.
LINEMEDIAMODE_G4FAX
Calls of the group 4 fax media type.
LINEMEDIAMODE_DIGITALDATA
Calls of the digital data media type.
LINEMEDIAMODE_TELETEX
Calls with the teletex media mode.
LINEMEDIAMODE_VIDEOTEX
Calls with the videotex media mode.
LINEMEDIAMODE_TELEX
Calls with the telex media mode.
LINEMEDIAMODE_MIXED
Calls with the ISDN mixed media mode.
LINEMEDIAMODE_ADSI
Calls with the ADSI (Analog Display Services Interface) media mode.
LINEMEDIAMODE_VOICEVIEW
Calls with the VoiceView media mode.
lpCallParams
A pointer to a structure of type LINECALLPARAMS. It describes the call parameters that the line device should be able to provide. The only relevant fields of lpCallParams for the purposes of this test are the following:

dwBearerMode

dwMinRate

dwMaxRate

dwMediaMode

dwCallParamFlags

dwAddressMode

If dwAddressMode is LINEADDRESSMODE_ADDRESSID, any address on the line is acceptable. If dwAddressMode is LINEADDRESSMODE_DIALABLEADDR, indicating that a specific originating address (phone number) is searched for, or if it is a provider-specific extension, then dwOrigAddressSize/Offset and the portion of the variable part they refer to are also relevant. If dwAddressMode is a provider-specific extension, additional information can be contained in the dwDeviceSpecific variably sized field. All other fields are irrelevant to the function.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NODRIVER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_INVALMEDIAMODE, LINEERR_OPERATIONUNAVAIL.

Remarks

A TAPI lineOpen function that specifies a device identifier of LINEMAPPER typically results in calling this procedure for multiple line devices to hunt for a suitable line, possibly also opening as-yet unopened lines. A success result indicates that the line is suitable for the calling application's requirements.

Note The media monitoring modes demanded at the TSPI level are the union of monitoring modes demanded by multiple applications at the TAPI level. As a consequence, it is most common for multiple media mode flags to be set simultaneously at this level. The service provider must test to determine if it can support at least the specified set, regardless of what modes are currently in effect. TAPI ensures that the dwMediaModes parameter has at least one bit set and that no reserved bits are set. It is the service provider's responsibility to do any further validity checks on the media modes, such as checking whether any media modes are supported by the service provider.

The TSPI_lineConditionalMediaDetection function checks the bits set in the dwCallParamFlags member of the LINECALLPARAMS structure and handles the following cases:

The TSPI_lineConditionalMediaDetection function returns success if passing the same bit values to the TSPI_lineMakeCall function would also return success.

If the SECURE, ORIGOFFHOOK, and DESTOFFHOOK bits are set and the dwAddressMode parameter is LINEADDRESSMODE_ADDRESSID, the function returns success if it can succeed on one or more addresses on the line.

If the SECURE, ORIGOFFHOOK, and DESTOFFHOOK bits are set and the dwAddressMode parameter is LINEADDRESSMODE_DIALABLEADDR, the function returns success if it can succeed on the address identified by the dwOrigAddress parameter.

The service provider returns an error (for example, LINEERR_RESOURCEUNAVAIL) if, at the time this function is called, it is impossible to place a new call on the specified line device (if it would return LINEERR_CALLUNAVAIL or LINEERR_RESOURCEUNAVAIL should TSPI_lineMakeCall be invoked immediately after opening the line).

There is no directly corresponding function at the TAPI level. This procedure corresponds to the test implied for each individual line by the lineOpen procedure when it is called with the device identifier LINEMAPPER.

See Also

LINECALLPARAMS, LINEMEDIAMODE_ Constants, TSPI_lineMakeCall


TSPI_lineConfigDialog

The TSPI_lineConfigDialog function is obsolete. TAPI version 1.4 or earlier service providers can implement this TSPI function. TAPI version 2.0 or later TSPs implement TUISPI_lineConfigDialog.

The TSPI_lineConfigDialog function causes the provider of the specified line device to display a modal dialog box as a child window of hwndOwner to allow the user to configure parameters related to the line device.

LONG TSPI_lineConfigDialog(
  DWORD dwDeviceID,
  HWND hwndOwner,
  LPCWSTR lpszDeviceClass
);

Parameters

dwDeviceID
The line device to be configured.
hwndOwner
A handle to a parent window in which the dialog box window is to be placed.
lpszDeviceClass
A pointer to a NULL-terminated string that identifies a device class name. This device class allows the caller to select a specific subscreen of configuration information applicable to that device class. If this parameter is NULL or an empty string, the highest level configuration dialog box should be selected. The permitted strings are the same as for TSPI_lineGetID. For example, if the line supports the Comm API, passing comm/datamodem as lpszDeviceClass causes the provider to display the parameters related specifically to Comm (or, at least, to start at the corresponding point in a multilevel configuration dialog box chain, so that the user doesn't have to search to find the desired parameters.)

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INUSE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

The procedure must update the [Windows Telephony] section in the win.ini file and broadcast the WM_WININICHANGE message if it makes any changes to the telephon.ini file that would cause a change in the line or address capabilities reported in LINEDEVCAPS or LINEADDRESSCAPS, or if a line device is created or removed.

There is no restriction that this function (TSPI_lineConfigDialog) be called only when the line is closed. However, each provider can impose such a restriction itself. When TSPI_lineConfigDialog is called, the provider could alert the user with the message "The line is in use by one or more applications. You may not change the line configuration while the line is in use" (and return the error message LINEERR_INUSE). However, some configuration may be safe to change "on the fly," particularly those related to media modes (such as the modem error control protocol), especially when that media mode is not currently in use. The provider could allow those options to be changed while the line is open.

Users should not be allowed to change anything that alters values returned with LINEDEVCAPS or LINEADDRESSCAPS without first forcibly closing the line as a signal that applications must call functions that return these structures in order to have accurate information.

See Also

LINEADDRESSCAPS, LINEDEVCAPS, TSPI_lineGetDevConfig, TSPI_lineGetID, TSPI_lineSetDevConfig


TSPI_lineConfigDialogEdit

The TSPI_lineConfigDialogEdit function is obsolete. TAPI version 1.4 or earlier service providers can implement this TSPI function. TAPI version 2.0 or later TSPs implement TUISPI_lineConfigDialogEdit.

The TSPI_lineConfigDialogEdit function causes the provider of the specified line device to display a modal dialog box as a child window of hwndOwner to allow the user to configure parameters related to the line device.

LONG TSPI_lineConfigDialogEdit(
  DWORD dwDeviceID,
  HWND hwndOwner,
  LPCWSTR lpszDeviceClass,
  LPVOID const lpDeviceConfigIn,
  DWORD dwSize,
  LPVARSTRING lpDeviceConfigOut
);

Parameters

dwDeviceID
The line device to be configured.
hwndOwner
A handle to a window to which the dialog box is to be attached.
lpszDeviceClass
A pointer to a NULL-terminated string that identifies a device class name. This device class allows the caller to select a specific subscreen of configuration information applicable to that device class. If this parameter is NULL or points to an empty string, the highest level configuration is selected. The permitted strings are the same as for TSPI_lineGetID.
lpDeviceConfigIn
A pointer to the opaque configuration data structure that was returned by TSPI_lineGetDevConfig (or a previous invocation of TSPI_lineConfigDialogEdit) in the variable portion of the VARSTRING structure.
dwSize
The number of bytes in the structure pointed to by lpDeviceConfigIn. This value is returned in the dwStringSize member in the VARSTRING structure returned by TSPI_lineGetDevConfig or a previous invocation of TSPI_lineConfigDialogEdit.
lpDeviceConfigOut
A pointer to the memory location of type VARSTRING where the device configuration structure is returned. Upon successful completion of the request, this location is filled with the device configuration. The dwStringFormat member in the VARSTRING structure is set to STRINGFORMAT_BINARY. Prior to calling lineGetDevConfig (or a future invocation of lineConfigDialogEdit), the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or an error number if an error occurs. Possible return values are:

LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM.

Remarks

This function causes the service provider to display a modal dialog box (attached to hwndOwner) to allow the user to configure parameters related to the line specified by dwDeviceID.

The lpszDeviceClass parameter selects a specific subscreen of configuration information applicable to the device class in which the user is interested; the permitted strings are the same as for TSPI_lineGetID. For example, if the line supports the Comm API, passing comm/datamodem as lpszDeviceClass causes the provider to display the parameters related specifically to Comm (or, at least, start at the corresponding point in a multilevel configuration dialog box chain, so the user doesn't have to "dig" to find the parameters of interest).

The lpszDeviceClass parameter is "tapi/line" , "", or NULL to cause the provider to display the highest level configuration for the line.

The difference between this function and TSPI_lineConfigDialog is the source of the parameters to edit and the result of the editing. In TSPI_lineConfigDialog, the parameters edited are those currently in use on the device (or set for use on the next call), and any changes made have (to the maximum extent possible) an immediate impact on any active connection; also, the application must use lineGetDevConfig to fetch the result of parameter changes from TSPI_lineConfigDialog. With TSPI_lineConfigDialogEdit, the parameters to edit are passed in from the application, and the results are returned to the application, with no impact on active connections; the results of the editing are returned with this function, and the application does not need to call lineGetDevConfig. Thus, TSPI_lineConfigDialogEdit permits an application to provide the ability for the user to set up parameters for future calls without having an impact on any active call. However, the output of this function can be passed to TSPI_lineSetDevConfig to affect the current call or next call.

For backward compatibility, this function is not exported by older service providers. TAPI detects this condition and reports LINEERR_OPERATIONUNAVAIL if an application attempts to call this function on an older provider.

See Also

TSPI_lineConfigDialog, TSPI_lineGetDevConfig, TSPI_lineGetID, TSPI_lineSetDevConfig, VARSTRING


TSPI_lineDevSpecific

The TSPI_lineDevSpecific function is used as a general extension mechanism to enable service providers to provide access to features not described in other operations. The meaning of the extensions are device-specific, and to take advantage of these extensions the application must be fully aware of them.

LONG TSPI_lineDevSpecific(
  DRV_REQUESTID dwRequestID,
  HDRVLINE hdLine,
  DWORD dwAddressID,
  HDRVCALL hdCall,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdLine
The service provider's handle to the line to be operated on.
dwAddressID
The address on the specified line to be operated on.
hdCall
The service provider's handle to the call to be operated on. This field may have the value NULL. The call state of hdCall is device specific.
lpParams
A pointer to a memory area used to hold a parameter block. The format of this parameter block is device specific.
dwSize
The size in bytes of the parameter block area.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

Additional return values are device specific.

This operation provides a generic parameter profile. The interpretation of the parameter structure is device specific. TAPI always specifies the hdLine parameter. Whether dwAddressID and/or hdCall are expected to be valid is device specific. If specified, they must belong to hdLine. Indications and replies sent back to the application that are device specific use the LINE_DEVSPECIFIC message.

This function is called in direct response to an application calling the TAPI function lineDevSpecific. TAPI translates the hLine and hCall parameters used at the TAPI level to the corresponding hdLine and hdCall parameters used at the TSPI level. The lpParams buffer is passed unmodified.

Note The lpParams data structure should not contain any pointers because they would not be properly translated (thunked) when running a 16-bit application in a 32-bit version of TAPI and vice versa.

A service provider can provide access to device-specific functions by defining parameters for use with this operation. Applications that want to make use of these device-specific extensions should consult the device-specific documentation (in this case meaning vendor-specific) that describes which extensions are defined.

Note An application that relies on device-specific extensions is not portable in working with other service provider environments. Use vendor-specific extensions.

This operation is part of the Extended Telephony services. It only provides access to a device-specific feature without defining its meaning. This operation is only available if the application has successfully negotiated and selected a device-specific extension version.

See Also

ASYNC_COMPLETION, LINE_DEVSPECIFIC, TSPI_lineNegotiateExtVersion


TSPI_lineDevSpecificFeature

The TSPI_lineDevSpecificFeature function is used as an extension mechanism to enable service providers to provide access to features not described in other operations. The meanings of these extensions are device specific, and taking advantage of these extensions requires TAPI or its client application to be fully aware of them.

LONG TSPI_lineDevSpecificFeature(
  DRV_REQUESTID dwRequestID,
  HDRVLINE hdLine,
  DWORD dwFeature,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdLine
The service provider's handle to the line device.
dwFeature
The feature to invoke on the line device. This parameter uses PHONEBUTTONFUNCTION_ constants.
lpParams
A pointer to a memory area used to hold a feature-dependent parameter block. The format of this parameter block is device specific.
dwSize
The size of the buffer in bytes.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALFEATURE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

Additional return values are device specific.The call state of hdCall is device-specific.

This function provides TAPI applications with phone feature button emulation capabilities. When TAPI invokes this operation on behalf of a client application, it specifies the equivalent of a "button press" event. This method of invoking features is highly device dependent, as the API does not define their meaning. When an application relies on device-specific extensions, the application does not port well to other service provider environments.

This function is called in direct response to an application calling the TAPI lineDevSpecificFeature function. TAPI translates the hLine parameter used at the TAPI level to the corresponding hdLine parameter used at the TSPI level. The lpParams buffer is passed through unmodified.

Note The lpParams data structure should not contain any pointers because they are not properly translated (thunked) when running a 16-bit application in a 32-bit version of TAPI and vice versa.

This operation is part of the Extended Telephony services. It only provides access to a device-specific feature without defining its meaning. This operation is only available if TAPI has successfully negotiated and selected a device-specific extension version.

See Also

ASYNC_COMPLETION, LINE_DEVSPECIFICFEATURE, PHONEBUTTONFUNCTION_ Constants


TSPI_lineDial

The TSPI_lineDial function dials the specified dialable number on the specified call.

LONG TSPI_lineDial(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPCWSTR lpszDestAddress,
  DWORD dwCountryCode
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The service provider's handle to the call to be dialed. The call state of hdCall can be any state except idle and disconnected.
lpszDestAddress
The destination to be dialed using the standard dialable number format.
dwCountryCode
The country code of the destination. This is used by the implementation to select the call progress protocols for the destination address. If a value of 0 is specified, a default call-progress protocol defined by the service provider is used. This parameter is not validated by TAPI when this function is called.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCOUNTRYCODE, LINEERR_DIALBILLING, LINEERR_INVALCALLSTATE, LINEERR_DIALQUIET, LINEERR_ADDRESSBLOCKED, LINEERR_DIALDIALTONE, LINEERR_NOMEM, LINEERR_DIALPROMPT, LINEERR_OPERATIONUNAVAIL.

Remarks

The service provider returns LINEERR_INVALCALLSTATE if the current state of the call does not allow dialing.

The service provider carries out no dialing if it returns LINEERR_INVALADDRESS.

If the service provider returns LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE, or LINEERR_DIALPROMPT, it should perform none of the actions otherwise performed by TSPI_lineDial (for example, no partial dialing, and no going offhook). This is because the service provider should pre-scan the number for unsupported characters first.

TSPI_lineDial is used for dialing on an existing call appearance; for example, call handles returned from TSPI_lineMakeCall with NULL as the lpszDestAddress or ending in ';', call handles returned from TSPI_lineSetupTransfer or TSPI_lineSetupConference. TSPI_lineDial can be invoked multiple times in the course of dialing in the case of multistage dialing, if the line's device capabilities permit it.

If the string pointed to by the lpszDestAddress parameter in the previous call to the TSPI_lineMakeCall or TSPI_lineDial function is terminated with a semicolon, an empty string in the current call to TSPI_lineDial indicates that dialing is complete.

Multiple addresses can be provided in a single dial string separated by CRLF. Service providers that provide inverse multiplexing can establish individual physical calls with each of the addresses, and return a single call handle to the aggregate of all calls to the application. All addresses would use the same country code.

Dialing is considered complete after the address has been accepted by the service provider, not after the call is finally connected. Service providers that provide inverse multiplexing may allow multiple addresses to be provided at once. The service provider must send LINE_CALLSTATE messages to TAPI to inform it about the progress of the call.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, TSPI_lineMakeCall


TSPI_lineDrop

The TSPI_lineDrop function drops or disconnects the specified call. User-user information can optionally be transmitted as part of the call disconnect. This function can be called by the application at any time. When TSPI_lineDrop returns, the call should be idle.

LONG TSPI_lineDrop(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPCSTR lpsUserUserInfo,
  DWORD dwSize
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The service provider's handle to the call to be dropped. The call state of hdCall can be any state except idle.
lpsUserUserInfo
This pointer is only valid if dwUserUserInfoSize is nonzero. It specifies a pointer to a string containing user-user information to be sent to the remote party as part of the call disconnect. This pointer is NULL if no user-user information is to be sent. User-user information is only sent if supported by the underlying network (see LINEDEVCAPS).
dwSize
The size in bytes of the user-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, dwSize is ignored.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_USERUSERINFOTOOBIG, LINEERR_OPERATIONUNAVAIL.

Remarks

The service provider returns LINEERR_INVALCALLSTATE if the current state of the call does not allow the call to be dropped.

When invoking TSPI_lineDrop, related calls can sometimes be affected as well. For example, dropping a conference call may drop all individual participating calls. LINE_CALLSTATE messages are sent to TAPI for all calls whose call state is affected. Typically, a dropped call transitions to the idle state. Invoking TSPI_lineDrop on a call in the offering state rejects the call. Not all telephone networks provide this capability.

In situations where the call to be dropped is a consultation call established during transfer or conference call establishment, the original call that was placed in the OnHoldPending state is reconnected to and it typically re-enters the connected call state.

TAPI has the option to send user-user information at the time of the drop. Even if user-user information can be sent, there is no guarantee that the network will deliver this information to the remote party.

Note In various bridged or party line configurations when multiple parties are on the call, TSPI_lineDrop may not actually clear the call.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINEDEVCAPS, TSPI_lineGetDevCaps


TSPI_lineDropNoOwner

The TSPI_lineDropNoOwner function is obsolete. TAPI no longer automatically drops a call if no initial owner can be identified, in order to accommodate the distributed control of calls across multiple client machines in a client/server environment.


TSPI_lineDropOnClose

The TSPI_lineDropOnClose function is obsolete. TAPI no longer automatically drops a call when the sole owner closes its handle to the line device, in order to accommodate the distributed control of calls across multiple client machines in a client/server environment.


TSPI_lineForward

The TSPI_lineForward function forwards calls destined for the specified address on the specified line, according to the specified forwarding instructions. When an originating address (dwAddressID) is forwarded, the specified incoming calls for that address are deflected to the other number by the switch. This function provides a combination of forward and do-not-disturb features. This function can also cancel specific forwarding currently in effect.

LONG TSPI_lineForward(
  DRV_REQUESTID dwRequestID,
  HDRVLINE hdLine,
  DWORD bAllAddresses,
  DWORD dwAddressID,
  LPLINEFORWARDLIST const lpForwardList,
  DWORD dwNumRingsNoAnswer,
  HTAPICALL htConsultCall,
  LPHDRVCALL lphdConsultCall,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdLine
The service provider's handle to the line to be forwarded.
bAllAddresses
Specifies whether all originating addresses on the line or just the one specified is to be forwarded. If TRUE, all addresses on the line are forwarded and dwAddressID is ignored; if FALSE, only the address specified as dwAddressID is forwarded. This parameter is not validated by TAPI when this function is called.
dwAddressID
The address on the specified line whose incoming calls are to be forwarded. This parameter is ignored if bAllAddresses is TRUE. This parameter is not validated by TAPI when this function is called.
lpForwardList
A pointer to a variably sized data structure of type LINEFORWARDLIST that describes the specific forwarding instructions.
dwNumRingsNoAnswer
Specifies the number of rings before an incoming call is considered a "no answer." If dwNumRingsNoAnswer is out of range, the actual value is set to the nearest value in the allowable range. This parameter is not validated by TAPI when this function is called.
htConsultCall
The TAPI handle to a new call, if such a call must be created by the service provider. In some telephony environments, forwarding a call has the side effect of creating a consultation call used to consult the party that is being forwarded to. In such an environment, the service provider creates the new consutation call and must save this value and use it in all subsequent calls to the LINEEVENT procedure reporting events on the call. If no consultation call is created, this value can be ignored by the service provider.
lphdConsultCall
A pointer to an HDRVCALL representing the service provider's identifier for the call. In telephony environments where forwarding a call has the side effect of creating a consultation call used to consult the party that is being forwarded to, the service provider must fill this location with its handle for the call before this procedure returns. The service provider is permitted to do callbacks regarding the new call before it returns from this procedure. If no consultation call is created, the HDRVCALL must be left NULL.
lpCallParams
A pointer to a structure of type LINECALLPARAMS. This pointer is ignored by the service provider unless lineForward requires the establishment of a call to the forwarding destination (and lphdConsultCall is returned, in which case lpCallParams is optional). If NULL, default call parameters are used. Otherwise, the specified call parameters are used for establishing htConsultCall.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_STRUCTURETOOSMALL.

Remarks

The service provider returns LINEERR_INVALPARAM if the specified forward list parameter contains invalid information.

The service provider carries out no dialing if it returns LINEERR_INVALADDRESS.

The service provider returns success to this function to indicate only that the request is accepted by the service provider, not that forwarding is set up at the switch. A LINE_ADDRESSSTATE (forwarding) message is sent to provide that forwarding is set up at the switch.

Forwarding of the address or addresses remains in effect until this function is called again. The most recent forwarding list replaces any old one in effect. If this function is called, specifying a NULL pointer as lpForwardList, the service provider should cancel any forwarding that is being performed at that time. If a NULL destination address is specified for an entry in the forwarding list, the operation acts as a "do-not-disturb."

Forwarding status of an address may also be affected externally, for example, through administrative actions at the switch, or by a user from another station. It may not be possible for the service provider to be aware of this state change, and may not be able to keep in sync with the forwarding state known to the switch. The provider must always indicate what it knows to be true, and indicate that the forwarding state is unknown otherwise.

Because a service provider may not know the forwarding state of the address with no doubt (that is, it may have been forwarded or unforwarded in an unknown way), TSPI_lineForward succeeds unless it fails to set the new forwarding instructions. In other words, a request that all forwarding be canceled at a time when there is no forwarding in effect succeeds. This is because there is no unforwarding; you can only invoke a new set of forwarding instructions.

The success or failure of this operation does not depend on the previous set of forwarding instructions, and the same is true when setting different forwarding instructions. If necessary, the provider should "unforward everything" prior to setting the new forwarding instructions. Because this may take time in analog telephony environments, a provider may also want to compare the current forwarding with the new one, and only issue instructions to the switch to get to the final state (leaving unchanged forwarding unaffected).

Invoking TSPI_lineForward when LINEFORWARDLIST has dwNumEntries set to zero has the same effect as providing a NULL lpForwardList parameter; it cancels all forwarding currently in effect.

Because the NULL value returned into lphdConsultCall is the only way for TAPI to determine whether the service provider created a consultation call, the service provider cannot use NULL as a call handle.

This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETION reports success. In other words, it must not issue any messages for the new call or include it in call counts in messages or status data structures for the line.

See Also

ASYNC_COMPLETION, LINE_ADDRESSSTATE, LINECALLPARAMS, LINEEVENT, LINEFORWARDLIST


TSPI_lineGatherDigits

The TSPI_lineGatherDigits function initiates the buffered gathering of digits on the specified call. TAPI specifies a buffer in which to place the digits and the maximum number of digits to be collected.

LONG TSPI_lineGatherDigits(
  HDRVCALL hdCall,
  DWORD dwEndToEndID,
  DWORD dwDigitModes,
  LPWSTR lpsDigits,
  DWORD dwNumDigits,
  LPCWSTR lpszTerminationDigits,
  DWORD dwFirstDigitTimeout,
  DWORD dwInterDigitTimeout
);

Parameters

hdCall
The service provider's handle to the call on which digit gathering is to be performed. The call state of hdCall can be any state except idle.
dwEndToEndID
A unique, uninterpreted identifier of the request for its entire lifetime, that is, until the matching LINE_GATHERDIGITS message is sent. The service provider includes this identifier as one of the parameters in the message.
dwDigitModes
The digit mode(s) that are to be monitored. This parameter uses one or more of the following LINEDIGITMODE_ contants:
LINEDIGITMODE_PULSE
Detect digits as audible clicks that are the result of the use of rotary pulse sequences. Valid digits for pulse mode are '0' through '9'.
LINEDIGITMODE_DTMF
Detect digits as DTMF tones. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.
lpsDigits
A pointer to the buffer where detected digits are to be stored as ASCII characters. The service provider may, but is not required to, place digits in the buffer one at a time as they are collected. When the LINE_GATHERDIGITS message is sent, the content of the buffer must be complete. If lpsDigits is specified as NULL the digit gathering currently in progress on the call is canceled and the dwNumDigits parameter is ignored. Otherwise, lpsDigits is assumed to have room for dwNumDigits digits.
dwNumDigits
The number of digits to be collected before a LINE_GATHERDIGITS message is sent to TAPI. The dwNumDigits parameter is ignored when lpsDigits is NULL. This function must return a LINEERR_INVALPARAM if dwNumDigits is zero.
lpszTerminationDigits
A NULL-terminated string of termination digits as ASCII characters. If one of the digits in the string is detected, that termination digit is appended to the buffer, digit collection is terminated, and the LINE_GATHERDIGITS message is sent to TAPI.

Valid characters for pulse mode are '0' through '9'. Valid characters for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'. If this pointer is NULL, or if it points to an empty string, the function behaves as though no termination digits were supplied.

dwFirstDigitTimeout
The time duration in milliseconds in which the first digit is expected. If the first digit is not received in this timeframe, digit collection is terminated and a LINE_GATHERDIGITS message is sent to TAPI. A single NULL character is written to the buffer, indicating no digits were received and the first digit timeout terminated digit gathering. The call's line device capabilities specifies the valid range for this parameter or indicates that timeouts are not supported. This parameter is not validated by TAPI when this function is called.
dwInterDigitTimeout
The maximum time duration in milliseconds between consecutive digits. If no digit is received in this timeframe, digit collection is terminated and a LINE_GATHERDIGITS message is sent to TAPI. A single NULL character is written to the buffer, indicating that an interdigit timeout terminated digit gathering. The LINEDEVCAPS structure must specify the the valid range for this parameter or indicate that timeouts are not supported. This parameter is not validated by TAPI when this function is called.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_NOMEM, LINEERR_INVALTIMEOUT, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM.

Remarks

The service provider returns LINEERR_INVALPARAM if the dwNumDigits parameter is invalid.

This function returns zero (success) if digit collection is correctly initiated; not if digit collection has terminated. In all cases where a partial buffer is returned, valid digits (if any) are followed by an Unicode NULL character.

Digit collection can be terminated in the following ways:

  • The requested number of digits may have been collected.
  • One of the digits detected matches a digit in szTerminationDigits before the specified number of digits has been collected. The detected termination digit is also placed in the buffer and the partial buffer is returned.
  • One of the timeouts expires. The dwFirstDigitTimeout expires if the first digit is not received in this time period. The dwInterDigitTimout expires if the second, third, (and so forth) digit is not received within that time period from the previously detected digit, and a partial buffer is returned.
  • Calling this operation again while collection is in progress. The old collection session is terminated and the contents of the old buffer is undefined. To cancel digit gathering without initiating another operation, this operation is invoked with lpsDigits equal to NULL.

Although this function can be invoked in any call state except idle, digits can typically only be gathered while the call is in the connected state.

The LINE_GATHERDIGITS message is normally sent when the digit buffer becomes filled. It is also sent when partial buffers are returned because of timeouts or matching termination digits, or when the request is canceled through another TSPI_lineGatherDigits request on the call. Only one gather digits request can be active at a time. The service provider must terminate any outstanding gathering operation with a LINE_GATHERDIGITS message when TSPI_lineGatherDigits is called.

When the operation associated with a call to the TSPI_lineGatherDigits function is canceled (by a subsequent call to the function), the service provider copies any digits collected up to that point to the buffer specified in the original call.

TAPI can use TSPI_lineMonitorDigits to enable or disable unbuffered digit detection. Each time a digit is detected in this fashion, a LINE_MONITORDIGITS message is sent to TAPI. Both buffered (gather digits) and unbuffered digit detection can be enabled for the same call simultaneously.

The service provider is allowed some variation in the quality of timing it uses for this function, including not doing timings at all. The quality of timing is reported in LINEDEVCAPS, in the members dwGatherDigitsMinTimeout and dwGatherDigitsMaxTimeout.

The corresponding function at the TAPI level does not include the formal parameter dwEndToEndID. At that level, there is no end-to-end marking. TAPI uses end-to-end marking at the TSPI level to distinguish one TSPI_lineGatherDigits request from another.

See Also

LINE_GATHERDIGITS, LINE_MONITORDIGITS, LINEDEVCAPS, LINEDIGITMODE_ Constants, TSPI_lineGetDevCaps, TSPI_lineMonitorDigits


TSPI_lineGenerateDigits

The TSPI_lineGenerateDigits function initiates the generation of the specified digits on the specified call as in-band tones using the specified signaling mode. Invoking this function while digit or tone generation is in progress aborts the current digit or tone generation. Passing a NULL value for lpsDigits generates no new digits.

Note Only one inband generation request at a time (tone generation or digit generation) can be in progress per call.

LONG TSPI_lineGenerateDigits(
  HDRVCALL hdCall,
  DWORD dwEndToEndID,
  DWORD dwDigitMode,
  LPCWSTR lpszDigits,
  DWORD dwDuration
);

Parameters

hdCall
The handle to the call on which digit generation is to be done.
dwEndToEndID
This unique request identifier should be stored by the service provider and passed back as dwParam2 to the LINEEVENT procedure when the digit generation is completed.
dwDigitMode
The format to be used for signaling these digits. This parameter is allowed to have only one of the following LINEDIGITMODE_ constants set:
LINEDIGITMODE_PULSE
Use pulse/rotary for digit signaling. Valid digits for pulse mode are '0' through '9', '!', and ',' (comma). The '!' indicates a "hookflash" operation.
LINEDIGITMODE_DTMF
Use DTMF tones for digit signaling. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#', '!', and ',' (comma). The '!' indicates a "hookflash" operation.
lpszDigits
A pointer to a NULL-terminated character buffer that contains the digits to be generated. A comma injects an extra delay between the signaling of the previous and next digits it separates. The duration of this pause is configuration defined. The line's device capabilities indicate what this duration is. Multiple commas can be used to inject longer pauses. Invalid digits are ignored during the generation, rather than being reported as an error.
dwDuration
Specifies both the duration in milliseconds of DTMF digits and pulse and DTMF inter-digit spacing. A value of 0 uses a default value. The dwDuration parameter must be within the range specified by MinDialParams to MaxDialParams in LINEDEVCAPS. If out of range, the actual value is set by the service provider to the nearest value in the range. This parameter is not validated by TAPI when this function is called.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONFAILED, LINEERR_RESOURCEUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Remarks

The call state of hdCall can be any state.

The TSPI_lineGenerateDigits function is considered to have completed successfully when the digit generation is successfully initiated; not when all digits are generated.

After all digits in lpsDigits are generated, or after digit generation is aborted or canceled, a LINE_GENERATE message is sent to TAPI.

Note Only one inband generation request (tone generation or digit generation) is allowed to be in progress per call. This implies that if digit generation is currently in progress on a call, invoking either TSPI_lineGenerateDigits or TSPI_lineGenerateTone cancels the digit generation. The service provider must terminate any digit generation in progress when a subsequent TSPI_lineGenerateDigits or TSPI_lineGenerateTone is invoked. Invoking TSPI_lineGenerateDigits with lpszDigits set to NULL cancels any current digit (or tone) generation.

The corresponding function at the TAPI level does not include the formal parameter dwEndToEndID. At that level, there is no end-to-end marking. TAPI uses end-to-end marking at the TSPI level to disambiguate one TSPI_lineGenerateDigits request from another.

See Also

LINE_GENERATE, LINEDEVCAPS, LINEDIGITMODE_ Constants, LINEEVENT, TSPI_lineGenerateTone


TSPI_lineGenerateTone

The TSPI_lineGenerateTone function generates the specified tone inband over the specified call. Invoking this function with a zero for dwToneMode aborts any tone generation currently in progress on the specified call. Invoking TSPI_lineGenerateTone or TSPI_lineGenerateDigits while tone generation is in progress aborts the current tone generation or digit generation in progress and initiates the generation of the newly specified tone or digits.

LONG TSPI_lineGenerateTone(
  HDRVCALL hdCall,
  DWORD dwEndToEndID,
  DWORD dwToneMode,
  DWORD dwDuration,
  DWORD dwNumTones,
  LPLINEGENERATETONE const lpTones
);

Parameters

hdCall
The service provider's handle to the call on which tone generation is to be performed. The call state of hdCall can be any state except idle.
dwEndToEndID
A unique, uninterpreted identifier of the request for its entire lifetime, that is, until the matching LINE_GENERATE message is sent. The service provider includes this identifier as one of the parameters in the message.
dwToneMode
Defines the tone to be generated. Tones can be either standard or custom. A custom tone is composed of a set of arbitrary frequencies. A small number of standard tones are predefined. The duration of the tone is specified by dwDuration for both standard and custom tones. If dwToneMode is set to zero, any digit or tone generation in progress is canceled. This parameter uses the following LINETONEMODE_ constants. Only one flag value can be set at a time:
LINETONEMODE_CUSTOM
The tone is a custom tone, defined by the specified frequencies.
LINETONEMODE_RINGBACK
The tone to be generated is a ring tone. The exact ringback tone is service provider defined.
LINETONEMODE_BUSY
The tone is a standard (station) busy tone. The exact busy tone is service provider defined.
LINETONEMODE_BEEP
The tone is a beep, as used to announce the beginning of a recording. The exact beep tone is service provider defined.
LINETONEMODE_BILLING
The tone is a billing information tone such as a credit card prompt tone. The exact billing tone is service provider defined.
dwDuration
The duration in milliseconds during which the tone is sustained. A value of 0 for dwDuration uses a default duration for the specified tone. Default values are:

CUSTOM: infinite

RINGBACK: infinite

BUSY: infinite

BEEP: infinite

BILLING: fixed (single cycle)

This parameter is not validated by TAPI when this function is called.

dwNumTones
The number of entries in the lpTones array. This parameter is ignored if dwToneMode is not equal to LINETONEMODE_CUSTOM.
lpTones
A pointer to a LINEGENERATETONE array that specifies the tone's components. This parameter is ignored for noncustom tones. If lpTones is a multifrequency tone, the various tones are played simultaneously.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALTONEMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALTONE, LINEERR_RESOURCEUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Remarks

TSPI_lineGenerateTone returns zero (success) when the tone generation is successfully initiated; not when the generation of the tone is finished. The function allows the inband generation of several predefined tones, such as ringback, busy tones, and beep. It also allows for the fabrication of custom tones by specifying their component frequencies, cadence and volume, if this is supported by the service provider. Because these tones are generated as inband tones, the call would typically have to be in the connected state for tone generation to be effective. When tone generation is complete, or when tone generation is canceled, a LINE_GENERATE message is sent to TAPI.

Note Only one inband generation request (tone generation or digit generation) is allowed to be in progress per call. This implies that if tone generation is currently in progress on a call, invoking either TSPI_lineGenerateDigits or TSPI_lineGenerateTone cancels the tone generation. The service provider must terminate any tone generation in progress when a subsequent TSPI_lineGenerateDigits or TSPI_lineGenerateTone function is invoked.

The corresponding function at the TAPI level does not include the formal parameter dwEndToEndID. At that level, there is no end-to-end marking. TAPI uses end-to-end marking at the TSPI level to distinguish one TSPI_lineGenerateTone request from another.

See Also

LINE_GENERATE, LINEGENERATETONE, LINETONEMODE_ Constants, TSPI_lineGenerateDigits


TSPI_lineGetAddressCaps

The TSPI_lineGetAddressCaps function queries the specified address on the specified line device to determine its telephony capabilities.

LONG TSPI_lineGetAddressCaps(
  DWORD dwDeviceID,
  DWORD dwAddressID,
  DWORD dwTSPIVersion,
  DWORD dwExtVersion,
  LPLINEADDRESSCAPS lpAddressCaps
);

Parameters

dwDeviceID
The line device containing the address to be queried.
dwAddressID
The address on the given line device whose capabilities are to be queried. This parameter is not validated by TAPI when this function is called.
dwTSPIVersion
The version number of the Telephony SPI to be used. The high-order word contains the major version number; the low-order word contains the minor version number.
dwExtVersion
The version number of the service-provider specific extensions to be used. This number is zero if no device-specific extensions are to be used. Otherwise, the high-order word contains the major version number; the low-order word contain the minor version number. This parameter is not validated by TAPI when this function is called.
lpAddressCaps
A pointer to a variably sized structure of type LINEADDRESSCAPS. Upon successful completion of the request, this structure is filled with address capabilities information.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_NODRIVER, LINEERR_RESOURCEUNAVAIL.

Remarks

The line device identifiers supported by a particular driver are numbered sequentially starting with the value of dwLineDeviceIDBase that is passed into the TSPI_providerInit function.

The service provider fills in all the members of the LINEADDRESSCAPS data structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSize member.

After the service provider returns from the TSPI_lineGetAddressCaps function, TAPI sets the dwCallInfoStates and dwCallStates members of the LINEADDRESSCAPS structure as follows:

LINEADDRESSCAPS.dwCallInfoStates |=
    LINECALLINFOSTATE_NUMOWNERINCR |
    LINECALLINFOSTATE_NUMOWNERDECR |
    LINECALLINFOSTATE_NUMMONITORS;

LINEADDRESSCAPS.dwCallStates |= LINECALLSTATE_UNKNOWN;

See Also

LINEADDRESSCAPS, TSPI_providerInit


TSPI_lineGetAddressID

The TSPI_lineGetAddressID function returns the address identifier associated with address in a different format on the specified line.

LONG TSPI_lineGetAddressID(
  HDRVLINE hdLine,
  LPDWORD lpdwAddressID,
  DWORD dwAddressMode,
  LPCWSTR lpsAddress,
  DWORD dwSize
);

Parameters

hdLine
The service provider's handle to the line whose address is to be retrieved.
lpdwAddressID
A pointer to a DWORD-sized memory location where the address identifier is returned.
dwAddressMode
The address mode of the address contained in lpsAddress. The dwAddressMode parameter is allowed to have only the following LINEADDRESSMODE_ flag set:
LINEADDRESSMODE_DIALABLEADDR
The address is specified using its dialable address. lpsAddress is the dialable address format.
lpsAddress
A pointer to a data structure holding the address assigned to the specified line device. The format of the address is determined by the dwAddressMode parameter. If it is LINEADDRESSMODE_DIALABLEADDR, the lpsAddress parameter uses the common dialable number format and is NULL terminated.
dwSize
The size of the address contained in lpsAddress. The parameter dwSize must be set to the length of the string (plus one for the NULL) if LINEADDRESSMODE_DIALABLEADDR is used. If an extended LINEADDRESSMODE is used, the length should match the size of whatever is actually passed in (the DLL checks to be sure it can read the number of bytes specified from the given pointer).

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

This function is used to map a phone number (address) assigned to a line device back to its dwAddressID (in the range from 0 through the number of addresses minus one) that is returned in the line's device capabilities.

See Also

LINEADDRESSMODE_ Constants


TSPI_lineGetAddressStatus

The TSPI_lineGetAddressStatus function queries the specified address for its current status.

LONG TSPI_lineGetAddressStatus(
  HDRVLINE hdLine,
  DWORD dwAddressID,
  LPLINEADDRESSSTATUS lpAddressStatus
);

Parameters

hdLine
The service provider's handle to the line containing the address to be queried.
dwAddressID
An address on the given open line device. This is the address to be queried. This parameter is not validated by TAPI when this function is called.
lpAddressStatus
A pointer to a variably sized data structure of type LINEADDRESSSTATUS.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

The service provider fills in all the members of the LINEADDRESSSTATUS data structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSize member.

See Also

LINEADDRESSSTATUS


TSPI_lineGetCallAddressID

The TSPI_lineGetCallAddressID function retrieves the address identifier for the indicated call.

LONG TSPI_lineGetCallAddressID(
  HDRVCALL hdCall,
  LPDWORD lpdwAddressID
);

Parameters

hdCall
The service provider's handle to the call whose address identifier is to be retrieved. The call state of hdCall can be any state.
lpdwAddressID
A pointer to a DWORD into which the service provider writes the call's address identifier.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Remarks

If the service provider models lines as "pools" of channel resources and does inverse multiplexing of a call over several address identifiers it should consistently choose one of these address identifiers as the primary identifier reported by this function and in the LINECALLINFO data structure.

This function has no direct correspondence at the TAPI level. It gives TAPI sufficient information to implement the lineGetNewCalls function invoked with the LINECALLSELECT_ADDRESS option.

See Also

LINECALLINFO


TSPI_lineGetCallInfo

The TSPI_lineGetCallInfo function returns detailed information about the specified call.

LONG TSPI_lineGetCallInfo(
  HDRVCALL hdCall,
  LPLINECALLINFO lpCallInfo
);

Parameters

hdCall
The service provider's handle to the call whose call information is to be retrieved. The call state of hdCall can be any state.
lpCallInfo
A pointer to a variably sized data structure of type LINECALLINFO. Upon successful completion of the request, this structure is filled with call-related information.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_OPERATIONUNAVAIL.

Remarks

The following table indicates which members of the LINECALLINFO data structure are filled in by TAPI and which members are filled in by the service provider. The service provider must preserve (it must not overwrite) the values filled in by TAPI.

Member | TAPI | Service Provider
dwTotalSize; | X |
dwNeededSize; |  | X
dwUsedSize; |  | X
hLine; | X |
dwLineDeviceID; |  | X
dwAddressID; |  | X
dwBearerMode; |  | X
dwRate; |  | X
dwMediaMode; |  | X
dwAppSpecific; |  | X
dwCallID; |  | X
dwRelatedCallID; |  | X
dwCallParamFlags; |  | X
dwCallStates; | X | X
dwMonitorDigitModes; | X |
dwMonitorMediaModes; | X |
DialParams; |  | X
dwOrigin; |  | X
dwReason; |  | X
dwCompletionID; |  | X
dwNumOwners; | X |
dwNumMonitors; | X |
dwCountryCode; |  | X
dwTrunk; |  | X
dwCallerIDFlags; |  | X
dwCallerIDSize; |  | X
dwCallerIDOffset; |  | X
dwCallerIDNameSize; |  | X
dwCallerIDNameOffset; |  | X
dwCalledIDFlags; |  | X
dwCalledIDSize; |  | X
dwCalledIDOffset; |  | X
dwCalledIDNameSize; |  | X
dwCalledIDNameOffset; |  | X
dwConnectedIDFlags; |  | X
dwConnectedIDSize; |  | X
dwConnectedIDOffset; |  | X
dwConnectedIDNameSize; |  | X
dwConnectedIDNameOffset; |  | X
dwRedirectionIDFlags; |  | X
dwRedirectionIDSize; |  | X
dwRedirectionIDOffset; |  | X
dwRedirectionIDNameSize; |  | X
dwRedirectionIDNameOffset; |  | X
dwRedirectingIDFlags; |  | X
dwRedirectingIDSize; |  | X
dwRedirectingIDOffset; |  | X
dwRedirectingIDNameSize; |  | X
dwRedirectingIDNameOffset; |  | X
dwAppNameSize; | X |
dwAppNameOffset; | X |
dwDisplayableAddressSize; | X |
dwDisplayableAddressOffset; | X |
dwCalledPartySize; | X |
dwCalledPartyOffset; | X |
dwCommentSize; | X |
dwCommentOffset; | X |
dwDisplaySize; |  | X
dwDisplayOffset; |  | X
dwUserUserInfoSize; |  | X
dwUserUserInfoOffset; |  | X
dwHighLevelCompSize; |  | X
dwHighLevelCompOffset; |  | X
dwLowLevelCompSize; |  | X
dwLowLevelCompOffset; |  | X
dwChargingInfoSize; |  | X
dwChargingInfoOffset; |  | X
dwTerminalModesSize; |  | X
dwTerminalModesOffset; |  | X
dwDevSpecificSize; |  | X
dwDevSpecificOffset; |  | X

TAPI fills in the size and offset fields for the dwAppNameSize/Offset, dwCalledPartySize/Offset, and dwCommentSize/Offset members and updates the value in dwUsedSize to reflect these after calling the service provider.

After the service provider returns from the TSPI_lineGetCallInfo function, TAPI sets the dwCallStates member of the LINECALLINFO structure as follows:

LINECALLINFO.dwCallStates |= LINECALLSTATE_UNKNOWN;

If the service provider models lines as "pools" of channel resources and does inverse multiplexing of a call over several address identifiers, it should consistently choose one of these address identifiers as the primary identifier reported by this function in the LINECALLINFO data structure.


TSPI_lineGetCallStatus

The TSPI_lineGetCallStatus function returns the current status of the specified call.

LONG TSPI_lineGetCallStatus(
  HDRVCALL hdCall,
  LPLINECALLSTATUS lpCallStatus
);

Parameters

hdCall
The service provider's handle to the call to be queried for its status. The call state of hdCall can be any state.
lpCallStatus
A pointer to a variably sized data structure of type LINECALLSTATUS. This structure is filled with call status information.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_OPERATIONUNAVAIL.

Remarks

The following table indicates which fields of the LINECALLSTATUS data structure are filled in by the service provider and which fields are filled in by TAPI. The service provider must preserve (it must not overwrite) the values filled in by TAPI.

Field Name | TAPI | Service Provider
dwTotalSize; | X |
dwNeededSize; |  | X
dwUsedSize; |  | X
dwCallState; |  | X
dwCallStateMode; |  | X
dwCallPrivilege; | X |
dwCallFeatures; |  | X
dwDevSpecificSize; |  | X
dwDevSpecificOffset; |  | X

TSPI_lineGetCallStatus returns the dynamic status of a call, whereas TSPI_lineGetCallInfo returns primarily static information about a call. Call status information includes the current call state, detailed mode information related to the call while in this state (if any), as well as a list of the available TSPI functions TAPI can invoke on the call while the call is in this state.

See Also

LINECALLSTATUS, TSPI_lineGetCallInfo


TSPI_lineGetDevCaps

The TSPI_lineGetDevCaps function queries a specified line device to determine its telephony capabilities. The returned information is valid for all addresses on the line device.

LONG TSPI_lineGetDevCaps(
  DWORD dwDeviceID,
  DWORD dwTSPIVersion,
  DWORD dwExtVersion,
  LPLINEDEVCAPS lpLineDevCaps
);

Parameters

dwDeviceID
The line device to be queried.
dwTSPIVersion
The negotiated TSPI version number. This value has already been negotiated for this device through the TSPI_lineNegotiateTSPIVersion function.
dwExtVersion
The negotiated extension version number. This value has already been negotiated for this device through the TSPI_lineNegotiateExtVersion function. This parameter is not validated by TAPI when this function is called.
lpLineDevCaps
A pointer to a variably sized structure of type LINEDEVCAPS. Upon successful completion of the request, this structure is filled with line device capabilities information.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONUNAVAIL, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_NODRIVER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM.

Remarks

Line device identifier numbering for a service provider is sequential from the value set by the dwLineDeviceIDBase parameter that is passed to the TSPI_providerInit function.

The dwExtVersion formal parameter indicates the version number of the requested extension information. If it is zero, no extension information is requested. If it is nonzero, it holds a value that was negotiated for this device with the TSPI_lineNegotiateExtVersion function. The service provider fills in device- and vendor-specific extended information according to the extension version specified.

The service provider fills in all the members of the LINEDEVCAPS data structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSize member.

The service provider must fill in all members of the LINETERMCAPS data structure or structures embedded in the varying part of the LINEDEVCAPS data structure.

After the service provider returns from the TSPI_lineGetDevCaps function, TAPI sets the dwLinesStates member of the LINEDEVCAPS structure as follows:

LINEDEVCAPS.dwLineStates |=
    LINEDEVSTATE_OPEN |
    LINEDEVSTATE_CLOSE |
    LINEDEVSTATE_REINIT |
    LINEDEVSTATE_TRANSLATECHANGE;

See Also

LINEDEVCAPS, LINETERMCAPS, TSPI_lineNegotiateExtVersion, TSPI_lineNegotiateTSPIVersion, TSPI_providerInit


TSPI_lineGetDevConfig

The TSPI_lineGetDevConfig function returns a data structure object, the contents of which are specific to the line (service provider) and device class, giving the current configuration of a device associated one-to-one with the line device.

LONG TSPI_lineGetDevConfig(
  DWORD dwDeviceID,
  LPVARSTRING lpDeviceConfig,
  LPCWSTR lpszDeviceClass
);

Parameters

dwDeviceID
The line device to be configured.
lpDeviceConfig
A pointer to a data structure of type VARSTRING where the device configuration structure of the associated device is returned. Upon successful completion of the request, the service provider fills this data structure with the device configuration. The dwStringFormat member in the VARSTRING structure must be set to STRINGFORMAT_BINARY. If the dwTotalSize member of the VARSTRING structure pointed to by the lpDeviceConfig parameter is greater than or equal to the size of the fixed portion of the structure, the service provider sets the dwNeededSize member to the required size and returns zero.
lpszDeviceClass
A pointer to a NULL-terminated Unicode string that specifies the device class of the device whose configuration is requested. Valid device class strings are the same as those specified for the TSPI_lineGetID function when it is applied to a line device (dwSelect has the value LINECALLSELECT_LINE).

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALDEVICECLASS, LINEERR_NOMEM, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_OPERATIONFAILED, LINEERR_NODRIVER, LINEERR_RESOURCEUNAVAIL.

Remarks

The call state is device specific.

This function can be used to retrieve a data structure from the service provider that specifies the configuration of a device associated one-to-one with the line device. The lpszDeviceClass parameter selects which of among possibly several different classes of devices is to have its configuration retrieved. The set of supported classes is restricted to those whose devices correspond one-to-one with the line device. For more information about common device classes, see TSPI Device Classes.

A service provider should typically allow the tapi/line device class under this function. It would retrieve parameters that have "line" scope, such as the list of addresses in this line, the list of physical hardware devices such as COMM ports corresponding to the addresses, maximum number of concurrent calls (if configurable), and so on.

In general, this function does not allow media-related device classes such as mci waveaudio, low level wave, or datamodem device classes, because these usually apply to a particular call or a particular address. Because there can be more than one of these per line device, the identification of the particular call or address simply by the line device identifier parameter in this function would be ambiguous. An exception can be made for call-specific or address-specific device classes in cases where there is class configuration information that applies to the entire line device scope, such as initial defaults, and so on.

There are several reasons why exceptional support for call-specific and address-specific device classes is of only limited value under this function. First, because these classes can be ambiguous on multiple-address/multiple-call service providers, only a subset of service providers support them. Applications are not likely to add a device-specific dependency on the inclusion of these classes in this function. Second, as higher-level media "classes" emerge that implement high-level protocols such as dial-in file system access in terms of low-level transport APIs, configuration for these classes tends toward "instance" scope instead of "class" scope. The high-level media API must supply its own functions to configure call-specific or address-specific instances.

Whatever sort of devices and device classes this function supports, it can potentially affect two kinds of configuration information: permanent and temporary. Permanent information survives across different "opens" of the line, and even across different "inits" of the service provider itself. Temporary information survives only within a unique "open" of the line. When the line is closed, any such temporary information that has been retrieved or set through TSPI_lineSetDevConfig can revert to default or undefined values. The caller can reliably retrieve any temporary configuration only by a sequence such as TSPI_lineOpen, TSPI_lineConfigDialog, TSPI_lineGetDevConfig. The caller can reliably set temporary configuration information retrieved by such a sequence through a sequence such as TSPI_lineOpen, TSPI_lineSetDevConfig. The temporary part of configuration remains stable only until the next TSPI_lineConfigDialog, TSPI_lineSetDevConfig, or TSPI_lineClose. The service provider must take care of storing any permanent part of the configuration, typically in an .ini file, and reloading it whenever the service provider is initialized.

The exact format of the data contained within the structure returned by this function is specific to the line and device class API, is undocumented, and is undefined. The structure returned by this function cannot be directly accessed or manipulated by the application, but can only be stored intact and later used in TSPI_lineSetDevConfig to restore the settings. The structure also cannot necessarily be passed to other devices, even of the same device class (although this may work in some instances, it is not guaranteed). A service provider should put items in the data structure to allow it to be checked for consistency to guard against failures due to a client application passing incompatible information.

See Also

TSPI_lineClose, TSPI_lineConfigDialog, TSPI_lineGetID, TSPI_lineOpen, TSPI_lineSetDevConfig, VARSTRING


TSPI_lineGetExtensionID

The TSPI_lineGetExtensionID function returns the extension identifier that the service provider supports for the indicated line device.

LONG TSPI_lineGetExtensionID(
  DWORD dwDeviceID,
  DWORD dwTSPIVersion,
  LPLINEEXTENSIONID lpExtensionID
);

Parameters

dwDeviceID
The line device to be queried.
dwTSPIVersion
An interface version number that was already negotiated for this device using TSPI_lineNegotiateTSPIVersion. This function operates according to the interface specification at this version level.
lpExtensionID
A pointer to a structure of type LINEEXTENSIONID. If the service provider supports provider-specific extensions, it fills this structure with the extension identifier of these extensions. If the service provider does not support extensions, it fills this structure with all zeros. (Therefore, a valid extension identifier cannot consist of all zeros.)

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Remarks

This function is typically called by TAPI in response to an application calling the lineNegotiateAPIVersion function. The result returned by the service provider should be appropriate for use in a subsequent call to TSPI_lineNegotiateExtVersion. An extension identifier of all zeros is not a legal extension identifier, because the all-zeros value is used to indicate that the service provider does not support extensions.

See Also

TSPI_lineNegotiateExtVersion, TSPI_lineNegotiateTSPIVersion


TSPI_lineGetIcon

The TSPI_lineGetIcon function retrieves a service line device-specific icon to display to the user.

LONG TSPI_lineGetIcon(
  DWORD dwDeviceID,
  LPCWSTR lpszDeviceClass,
  LPHICON lphIcon
);

Parameters

dwDeviceID
The line device whose icon is requested.
lpszDeviceClass
A pointer to a NULL-terminated string that identifies a device class name. This device class allows the caller to select an icon specific to that device class. This parameter is optional and can be left NULL, in which case the highest level icon associated with the line device rather than a specified media stream device is selected.

Permitted strings are the same as for TSPI_lineGetID. For example, if the line supports the Comm API, passing comm/datamodem as lpszDeviceClass causes the provider to return an icon related specifically to the Comm device functions of the service provider.

lphIcon
A pointer to a memory location in which the handle to the icon is returned.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_OPERATIONUNAVAIL.

Remarks

The provider should return a handle (in the DWORD pointed to by lphIcon) to an icon resource (obtained from the Win32 LoadIcon function) associated with the specified line.

A provider may choose to support many icons (selected by lpszDeviceClass and/or line number), a single icon (such as for the manufacturer, which would be returned for all TSPI_lineGetIcon requests regardless of the lpszDeviceClass selected), or no icons, in which case it sets the DWORD pointed to by lphIcon to NULL. TAPI examines the handle returned by the provider, and if the provider returns NULL, TAPI substitutes a generic Win32 Telephony icon (the generic "line" icon).

See Also

TSPI_lineConfigDialog, TSPI_lineGetID


TSPI_lineGetID

The TSPI_lineGetID function returns a device identifier for the specified device class associated with the selected line, address, or call.

LONG TSPI_lineGetID(
  HDRVLINE hdLine,
  DWORD dwAddressID,
  HDRVCALL hdCall,
  DWORD dwSelect,
  LPVARSTRING lpDeviceID,
  LPCWSTR lpszDeviceClass,
  HANDLE hTargetProcess
);

Parameters

hdLine
The service provider's handle to the line to be queried.
dwAddressID
An address on the given open line device. TAPI does not validate this parameter when this function is called.
hdCall
The service provider's handle to the call to be queried.
dwSelect
Specifies whether the device identifier requested is associated with the line, address, or a single call. The dwSelect parameter can only have one of the following LINECALLSELECT_ flags set:
LINECALLSELECT_LINE
Select the specified line device. The hdLine parameter must be a valid line handle; hdCall and dwAddressID are unused.
LINECALLSELECT_ADDRESS
Select the specified address on the line. Both hdLine and dwAddressID must be valid; hdCall is unused.
LINECALLSELECT_CALL
Select the specified call. The hdCall parameter must be valid; hdLine and dwAddressID are both unused.
lpDeviceID
A pointer to the memory location of type VARSTRING where the device identifier is returned. Upon successful completion of the request, this location is filled with the device identifier. The format of the returned information depends on the method used by the device class (API) for naming devices.
lpszDeviceClass
A pointer to a NULL-terminated Unicode string that specifies the device class of the device whose identifier is requested. Valid device class strings are those used in the system.ini section to identify device classes (such as COM, Wave, and MCI.)
hTargetProcess
The process handle of the application on behalf of which the TSPI_lineGetID function is invoked. If the information returned in the VARSTRING structure includes a handle for use by the application, the service provider should create or duplicate the handle for the process.

If hTargetProcess is set to INVALID_HANDLE_VALUE, then the application is executing on a remote client system and it is not possible to create a duplicate handle directly. Instead, the VARSTRING structure should contain a UNC name of a network device or other name that the remote client can use to access the device. If this is not possible, then the function should fail.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NODEVICE, LINEERR_RESOURCEUNAVAIL.

Remarks

The service provide returns LINEERR_INVALLINEHANDLE if dwSelect is LINECALLSELECT_LINE or LINECALLSELECT_ADDRESS, and hdLine is invalid.

The service provider returns LINEERR_INVALCALLHANDLE if dwSelect is LINECALLSELECT_CALL and hdCall is invalid.

The service provider should support the tapi/line device class to allow applications to determine the real line device identifier of an opened line. In that case, the variable data returned is the dwDeviceID. For more information about common device class names, see TSPI Device Classes.

A vendor that defines a device-specific media mode also needs to define the corresponding device-specific (proprietary) API to manage devices of the media mode. To avoid collisions on device class names assigned independently by different vendors, a vendor should select a name that uniquely identifies the vendor and then the media type; for example: "intel/video".

The service provider fills in all the members of the VARSTRING data structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSize member.

The service provider does not need to be concerned with handling tapi/line and tapi/phone device classes because TAPI handles these for the service provider. Therefore, code for handling these device classes is optional.

See Also

TSPI_lineGetDevConfig, TSPI_lineSetDevConfig, VARSTRING


TSPI_lineGetLineDevStatus

The TSPI_lineGetLineDevStatus function queries the specified open line device for its current status. The information returned is global to all addresses on the line.

LONG TSPI_lineGetLineDevStatus(
  HDRVLINE hdLine,
  LPLINEDEVSTATUS lpLineDevStatus
);

Parameters

hdLine
The service provider's handle to the line to be queried.
lpLineDevStatus
A pointer to a variably sized data structure of type LINEDEVSTATUS. This structure is filled with the line's device status.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_OPERATIONUNAVAIL.

Remarks

The following table indicates which members of the LINEDEVSTATUS data structure are filled in by TAPI and which are filled in by the service provider. The service provider must preserve (it must not overwrite) the values filled in by TAPI.

Member Name | TAPI | Service Provider
dwTotalSize; | X |
dwNeededSize; |  | X
dwUsedSize; |  | X
dwNumOpens; | X |
dwOpenMediaModes; | X |
dwNumActiveCalls; |  | X
dwNumOnHoldCalls; |  | X
dwNumOnHoldPendCalls; |  | X
dwLineFeatures; |  | X
dwNumCallCompletions; |  | X
dwRingMode; |  | X
dwSignalLevel; |  | X
dwBatteryLevel; |  | X
dwRoamMode; |  | X
dwDevStatusFlags; |  | X
dwTerminalModesSize; |  | X
dwTerminalModesOffset; |  | X
dwDevSpecificSize; |  | X
dwDevSpecificOffset; |  | X

See Also

LINEDEVSTATUS, TSPI_lineGetAddressStatus


TSPI_lineGetNumAddressIDs

The TSPI_lineGetNumAddressIDs function retrieves the number of address identifiers supported on the indicated line.

LONG TSPI_lineGetNumAddressIDs(
  HDRVLINE hdLine,
  LPDWORD lpdwNumAddressIDs
);

Parameters

hdLine
The handle to the line for which the number of address identifiers is to be retrieved.
lpdwNumAddressIDs
A pointer to a DWORD. The location is filled with the number of address identifiers supported on the indicated line. The value is one or larger.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_OPERATIONUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Remarks

This function is called by TAPI in response to an application calling lineSetNumRings, lineGetNumRings, or lineGetNewCalls. TAPI uses the retrieved value to determine if the specified address identifier is within the range supported by the service provider.


TSPI_lineHold

The TSPI_lineHold function places the specified call on hold.

LONG TSPI_lineHold(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The service provider's handle to the call to be placed on hold. The call state of hdCall can be connected.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

The call on hold is temporarily disconnected, allowing TAPI to use the line device for making or answering other calls. TSPI_lineHold performs a hard hold of the specified call, as opposed to a consultation call. A call on hard hold typically cannot be transferred or included in a conference call, whereas a consultation call can. Consultation calls are initiated using TSPI_lineSetupTransfer, TSPI_lineSetupConference, or TSPI_linePrepareAddToConference.

After a call is successfully placed on hold, the call state typically transitions to onHold. A held call is retrieved through TSPI_lineUnhold. While a call is on hold, the service provider can send LINE_CALLSTATE messages about state changes of the held call. For example, if the held party hangs up, the call state can transition to disconnected, and the service provider can send a LINE_CALLSTATE message indicating the new state.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, TSPI_lineSetupConference, TSPI_lineSetupTransfer, TSPI_lineUnhold


TSPI_lineMakeCall

The TSPI_lineMakeCall function places a call on the specified line to the specified destination address. Optionally, call parameters can be specified if anything but default call setup parameters are requested.

LONG TSPI_lineMakeCall(
  DRV_REQUESTID dwRequestID,
  HDRVLINE hdLine,
  HTAPICALL htCall,
  LPHDRVCALL lphdCall,
  LPCWSTR lpszDestAddress,
  DWORD dwCountryCode,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdLine
The handle to the line on which the new call is to be originated.
htCall
The TAPI handle to the new call. The service provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the call.
lphdCall
A pointer to a call handle. The service provider must fill this location with its handle for the call before this procedure returns. This handle is ignored by TAPI if the function results in an error.
lpszDestAddress
A pointer to the destination address. This follows the standard dialable number format. This pointer can be specified as NULL for non-dialed addresses (as with a hot phone, which always automatically connects to a predefined number) or when all dialing is performed using TSPI_lineDial. In the latter case, TSPI_lineMakeCall allocates an available call appearance that would typically remain in the dialtone state until dialing begins. Service providers that have inverse multiplexing capabilities can allow an application to specify multiple addresses at once.
dwCountryCode
The country code of the called party. If a value of 0 is specified, a default is used by the implementation.
lpCallParams
A pointer to a LINECALLPARAMS structure. This structure allows TAPI to specify how it wants the call to be set up. If NULL is specified, a default 3.1kHz voice call is established, and an arbitrary origination address on the line is selected. This structure selects elements such as the call's bearer mode, data rate, expected media mode, origination address, blocking of caller ID information, and dialing parameters.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_ADDRESSBLOCKED, LINEERR_INVALLINESTATE, LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALRATE, LINEERR_CALLUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_DIALBILLING, LINEERR_INVALADDRESS, LINEERR_DIALQUIET, LINEERR_INVALADDRESSID, LINEERR_DIALDIALTONE, LINEERR_INVALCALLPARAMS, LINEERR_DIALPROMPT, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALBEARERMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCOUNTRYCODE, LINEERR_RATEUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_USERUSERINFOTOOBIG.

Remarks

The service provider returns LINEERR_INVALLINESTATE if the line is currently not in a state in which this operation can be performed. A list of currently valid operations can be found in the dwLineFeatures member (of the type LINEFEATURE) in the LINEDEVSTATUS structure. (Calling TSPI_lineGetLineDevStatus updates the information in LINEDEVSTATUS.)

If the service provider returns LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE, or LINEERR_DIALPROMPT, it should perform none of the actions otherwise performed by TSPI_lineMakeCall. For example, no partial dialing, and no going offhook. This is because the service provider should pre-scan the number for unsupported characters first.

After TSPI_lineMakeCall returns a SUCCESS reply callback message to the application, the service provider must send LINE_CALLSTATE messages to the lpfnEventProc passed in TSPI_lineOpen to notify TAPI about the progress of the call. A typical reported sequence may be dial tone, dialing, proceeding, ringback, and connected; The first state reported is not necessarily LINECALLSTATE_DIALTONE. The service provider chooses how many of these states are reported. It is recommended that as many as possible are sent, so that applications can take appropriate actions.

The service provider initially does media monitoring on the new call for at least the set of media modes that were monitored for on the line.

If the dial string is NULL, the service provider takes the line to the dialtone state (for a Comm-based service provider, this would involve ATD) and send a call-state message indicating LINECALLSTATE_DIALTONE.

If the dial string ends in ';' (a semicolon), the service provider dials the partial number and sends the LINECALLSTATE_DIALING message. This call is completed by calls to TSPI_lineDial.

If the dial string contains characters (W, @, $, ?) that are not supported by the service provider, the service provider must scan the dial string and return (synchronously) an error corresponding to the first invalid character.

If the LINECALLPARAMFLAGS_IDLE flag is set, the service provider must check the current line status (the equivalent of going off-hook and sensing dial tone). If this IDLE flag is set and there is no dial tone, the function fails with the error LINEERR_CALLUNAVAIL. If the IDLE flag is not set, or there is a dial tone, the dialing can continue.

This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETION message reports success. It must not issue any LINEEVENT messages for the new call or include it in call counts in messages or status data structures for the line.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINECALLPARAMS, LINEEVENT, TSPI_lineDial, TSPI_lineDrop


TSPI_lineMonitorDigits

The TSPI_lineMonitorDigits function enables and disables the unbuffered detection of digits received on the call. Each time a digit of the specified digit mode(s) is detected, a LINE_MONITORDIGITS message is sent to the application by TAPI, indicating which digit is detected.

LONG TSPI_lineMonitorDigits(
  HDRVCALL hdCall,
  DWORD dwDigitModes
);

Parameters

hdCall
The handle to the call on which digits are to be detected. The call state of hdCall can be any state except idle or disconnected.
dwDigitModes
The digit mode(s) that are to be monitored. A dwDigitModes parameter with a value of 0 cancels digit monitoring. The dwDigitModes parameter can have any of the following LINEDIGITMODE_ flags set:
LINEDIGITMODE_PULSE
Detect digits as audible clicks that are the result of rotary pulse sequences. Valid digits for pulse are '0' through '9'. The LINE_MONITORDIGITS message is sent as soon after the last pulse of each digit as possible.
LINEDIGITMODE_DTMF
Detect digits as DTMF tones. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'. The LINE_MONITORDIGITS message is sent as soon after the onset of each tone as possible.
LINEDIGITMODE_DTMFEND
Detect and provide notification of DTMF down edges. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'. The LINE_MONITORDIGITS message is sent as soon as possible after the end of each digit, and before any indication of the beginning of a following digit.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM.

Remarks

This function returns zero (success) when digit monitoring is correctly initiated, not when digit monitoring is terminated. Digit monitoring remains in effect until it is explicitly disabled by a call to TSPI_lineMonitorDigits with dwDigitModes set to zero, or until the call transitions to idle. The function must return zero when digit monitoring is canceled (that is, when the dwDigitModes parameter is zero). The service provider must terminate digit monitoring when the call goes idle. TAPI does not spontaneously call TSPI_lineMonitorDigits to terminate monitoring.

Although this function can be invoked in any call state, digits typically are detected only while the call is in the connected state.

Each time a digit is detected, the service provider sends a LINE_MONITORDIGITS message to TAPI, passing the detected digit as a parameter. If both LINEDIGITMODE_DTMF and LINEDIGITMODE_DTMFEND are set in dwDigitModes, the two LINE_MONITORDIGITS messages are sent for each digit.

TAPI can use TSPI_lineMonitorDigits to enable or disable unbuffered digit detection. It can use TSPI_lineGatherDigits for buffered digit detection. After buffered digit gathering is complete, a LINE_GATHERDIGITS message is sent. Both buffered and unbuffered digit detection can be enabled on the same call simultaneously.

See Also

LINE_GATHERDIGITS, LINE_MONITORDIGITS, LINEDEVCAPS, LINEDIGITMODE_ Constants, TSPI_lineGatherDigits, TSPI_lineGetDevCaps, TSPI_lineSetMediaControl


TSPI_lineMonitorMedia

The TSPI_lineMonitorMedia function enables and disables the detection of media modes on the specified call. When a media mode is detected, a LINE_MONITORMEDIA message is sent to TAPI.

LONG TSPI_lineMonitorMedia(
  HDRVCALL hdCall,
  DWORD dwMediaModes
);

Parameters

hdCall
The handle to the call for which media monitoring is to be set. The call state of hdCall can be any state except idle.
dwMediaModes
The media modes to be monitored. The dwMediaModes parameter can have any of the following LINEMEDIAMODE_ flags set:
LINEMEDIAMODE_INTERACTIVEVOICE
One or more client applications wants to monitor the call for the presence of voice.

Note INTERACTIVEVOICE and AUTOMATEDVOICE are equivalent for monitoring purposes.

LINEMEDIAMODE_AUTOMATEDVOICE
One or more client applications wants to monitor the call for the presence of voice.

Note INTERACTIVEVOICE and AUTOMATEDVOICE are equivalent for monitoring purposes.

LINEMEDIAMODE_DATAMODEM
One or more client applications wants to monitor the call for the presence of data modem signals.
LINEMEDIAMODE_G3FAX
One or more client applications wants to monitor the call for the presence of group 3 fax signals.
LINEMEDIAMODE_TDD
One or more client applications wants to monitor the call for the presence of TDD (Telephony Devices for the Deaf) signals.
LINEMEDIAMODE_G4FAX
One or more client applications wants to monitor the call for the presence of group 4 fax signals.
LINEMEDIAMODE_DIGITALDATA
One or more client applications wants to monitor the call for the presence of unclassified digital data.
LINEMEDIAMODE_TELETEX
One or more client applications wants to monitor the call for the presence of teletex signals.
LINEMEDIAMODE_VIDEOTEX
One or more client applications wants to monitor the call for the presence of videotex signals.
LINEMEDIAMODE_TELEX
One or more client applications wants to monitor the call for the presence of telex signals.
LINEMEDIAMODE_MIXED
One or more client applications wants to monitor the call for the presence of ISDN mixed media data.
LINEMEDIAMODE_ADSI
One or more client applications wants to monitor the call for the presence of ADSI (Analog Display Services Interface) signals.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.

A value of 0 for the dwMediaModes parameter cancels all media mode monitoring.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM.

Remarks

The service provider returns LINEERR_INVALMEDIAMODE if the list of media types to be monitored contains invalid information.

This function returns zero (success) when media mode monitoring has been correctly initiated, not when media mode monitoring has terminated. Media monitoring for a given media mode remains in effect until it is explicitly disabled by calling TSPI_lineMonitorMedia with a dwMediaModes parameter with the media mode set to zero, or until the call transitions to idle.

TSPI_lineMonitorMedia is primarily an event reporting mechanism. The media mode of a call, as indicated in LINECALLINFO, is not affected by the service provider's detection of the media mode. Only TAPI or a client application can change a call's indicated media mode using TSPI_lineSetMediaMode. The actual use of a particular media mode occurs through separate media stream APIs (such as Comm or WAVE).

Default media monitoring performed by the service provider for a new call appearance corresponds to the union of all media modes specified by TSPI_lineSetDefaultMediaDetection. Shortly after a new call is established, TAPI typically calls TSPI_lineMonitorMedia to reduce the set of media modes detected and reported for this call to the union of all media modes desired by the call's client applications.

The service provider must cancel media monitoring when a call goes idle. TAPI must compute the union of media modes desired by all clients, and pass the result to this function. The service provider uses the set passed to this function by TAPI.

Although this function can be invoked in any call state, a call's media mode can typically only be detected while the call is in certain call states. These states can be device specific. For example, in ISDN a message can indicate the media mode of the media stream before the media stream exists. Similarly, distinctive ringing or the called ID information about the call can be used to identify the media mode of a call. Otherwise, the call may have to be answered (call in the connected state) to allow a service provider to determine the call's media mode by filtering of the media stream. Because filtering of a call's media stream implies a computational overhead, TAPI typically uses this procedure to disable media monitoring when it is not required.

Because media-mode detection enabled by TSPI_lineMonitorMedia is implemented as a read-only operation of the call's media stream, it is not disruptive. No signals are sent on the line as a result of setting TSPI_lineMonitorMedia.

Regarding the passed media mode, TAPI guarantees that there are no reserved bits set. The service provider must perform any further validity checks on the media modes, such as checking whether any media modes are indeed supported by the service provider.

See Also

LINE_MONITORMEDIA, LINECALLINFO, LINEDEVCAPS, LINEMEDIAMODE_ Constants TSPI_lineConditionalMediaDetection, TSPI_lineGetDevCaps, TSPI_lineSetDefaultMediaDetection, TSPI_lineSetMediaControl, TSPI_lineSetMediaMode


TSPI_lineMonitorTones

The TSPI_lineMonitorTones function enables and disables the detection of inband tones on the call. Each time a specified tone is detected, a message is sent to the client application through TAPI.

LONG TSPI_lineMonitorTones(
  HDRVCALL hdCall,
  DWORD dwToneListID,
  LPLINEMONITORTONE const lpToneList,
  DWORD dwNumEntries
);

Parameters

hdCall
The handle to the call for which tone detection is to be done. The call state of hdCall can be any state except idle.
dwToneListID
The unique identifier for this tone list. Several tone lists can be outstanding at one time. The service provider must replace any old list having the same dwToneListID with the new tone list. If lpToneList is NULL, the tone list with dwToneListID is simply dropped. In any case, other tone lists with different dwToneListIDs are kept unchanged.
lpToneList
A list of tones to be monitored, of type LINEMONITORTONE. Each tone in this list has an application-defined tag field that is used to identify individual tones in the list for the purpose of reporting a tone detection. Tone monitoring in progress is canceled or changed by calling this operation with either NULL for lpToneList or with another tone list. The service provider must copy the tone list into its own memory for later reference, rather than simply retaining the pointer into application memory.
dwNumEntries
The number of entries in lpToneList. The dwNumEntries parameter is ignored if lpToneList is NULL. TAPI does not validate this parameter when this function is called.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALTONE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_INVALPOINTER.

Remarks

This function returns zero (success) when tone monitoring is correctly initiated, not when tone monitoring is terminated. As with media monitoring, tone monitoring remains in effect for a given tone list until that tone list is explicitly disabled by calling TSPI_lineMonitorTones with the same dwToneListID and another tone list (or a NULL tone list), or until the call transitions to idle.

Although this function can be invoked in any call state except idle, tones can typically only be detected while the call is in the connected state. Tone detection usually requires computational resources. Depending on the service provider and other activities that compete for such resources, the number of tones that can be detected can vary over time. Also, an equivalent amount of resources can be consumed for monitoring a single triple frequency tone versus three single frequency tones. If resources are overcommitted, the service provider returns LINEERR_RESOURCEUNAVAIL.

The service provider monitors for all tones in all tone lists concurrently. When a tone is detected, each matching tone from each tone list is reported separately using a LINE_MONITORTONE message. Each tone report includes both the tone list identifier and the application-specific tag. Some service providers may not be able to discriminate very close tones, so that multiple matches may be reported even for tones whose descriptions are not strictly identical.

Note TSPI_lineMonitorTones is also used to detect silence. Silence is specified as a tone with all zero frequencies.

The corresponding function at the TAPI level does not include a dwToneListID parameter. The inclusion of this parameter at the TSPI interface allows TAPI to forward the union of all tone monitoring lists from all applications to the service provider, while still retaining the ability to filter and forward the tone detection events according to application. This gives service-provider designers the maximum flexibility to determine the degree to which they can discriminate very close tones, because TAPI makes no assumptions about what tone descriptions are considered identical.

See Also

LINE_MONITORTONE, LINEDEVCAPS, LINEMONITORTONE, TSPI_lineGetDevCaps, TSPI_lineSetMediaControl


TSPI_lineNegotiateExtVersion

The TSPI_lineNegotiateExtVersion function returns the highest extension version number the service provider can operate under for this device, given the range of possible extension versions.

LONG TSPI_lineNegotiateExtVersion(
  DWORD dwDeviceID,
  DWORD dwTSPIVersion,
  DWORD dwLowVersion,
  DWORD dwHighVersion,
  LPDWORD lpdwExtVersion
);

Parameters

dwDeviceID
Identifies the line device for which interface version negotiation is to be performed. The value INITIALIZE_NEGOTIATION may not be used for this function.
dwTSPIVersion
An interface version number that has already been negotiated for this device using TSPI_lineNegotiateTSPIVersion. This function operates according to the interface specification at this version level.
dwLowVersion
The lowest extension version number under which TAPI or its client application can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number. TAPI does not validate this parameter when this function is called.
dwHighVersion
The highest extension version number under which TAPI or its client application can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number. TAPI does not validate this parameter when this function is called.
lpdwExtVersion
A pointer to a DWORD. Upon a successful return from this function, the service provider fills this location with the highest extension version number, within the range requested by the caller, under which the service provider can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number. If the requested range does not overlap the range supported by the service provider, the function returns LINEERR_INCOMPATIBLEEXTVERSION.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONUNAVAIL, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_NODRIVER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM.

Remarks

This function can be called before or after the device is opened by TAPI. If the device is currently open and has an extension version selected, the function gives that version number if it is within the requested range. If the selected version number is outside the requested range, the function returns LINEERR_INCOMPATIBLEEXTVERSION.

See Also

INITIALIZE_NEGOTIATION, TSPI_lineNegotiateTSPIVersion


TSPI_lineNegotiateTSPIVersion

The TSPI_lineNegotiateTSPIVersion function returns the highest SPI version the service provider can operate under for this device, given the range of possible SPI versions.

LONG TSPI_lineNegotiateTSPIVersion(
  DWORD dwDeviceID,
  DWORD dwLowVersion,
  DWORD dwHighVersion,
  LPDWORD lpdwTSPIVersion
);

Parameters

dwDeviceID
Identifies the line device for which interface version negotiation is to be performed. In addition to device identifiers within the range the service provider supports, this may be the value:
INITIALIZE_NEGOTIATION
This value is used to signify that an overall interface version is to be negotiated.
dwLowVersion
The lowest TSPI version number under which TAPI can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number.
dwHighVersion
The highest TSPI version number under which TAPI can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number.
lpdwTSPIVersion
A pointer to a DWORD. The service provider fills this location with the highest TSPI version number, within the range requested by the caller, under which the service provider can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number. If the requested range does not overlap the range supported by the service provider, the function returns LINEERR_INCOMPATIBLEAPIVERSION.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONUNAVAIL, LINEERR_NODRIVER, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

When dwDeviceID is INITIALIZE_NEGOTIATION, this function must not return LINEERR_OPERATIONUNAVAIL, because this function (with that value) is mandatory for negotiating the overall interface version even if the service provider supports no line devices.

See Also

INITIALIZE_NEGOTIATION, TAPI Versions, TSPI_lineGetExtensionID, TSPI_lineNegotiateExtVersion, TSPI_providerInit


TSPI_lineOpen

The TSPI_lineOpen function opens the line device whose device identifier is given, returning the service provider's handle for the device. The service provider must retain the TAPI handle for the device for use in subsequent calls to the LINEEVENT callback procedure.

LONG TSPI_lineOpen(
  DWORD dwDeviceID,
  HTAPILINE htLine,
  LPHDRVLINE lphdLine,
  DWORD dwTSPIVersion,
  LINEEVENT lpfnEventProc
);

Parameters

dwDeviceID
Identifies the line device to be opened.
htLine
The TAPI handle for the line device to be used in subsequent calls to the LINEEVENT callback procedure to identify the device.
lphdLine
A pointer to an HDRVLINE where the service provider fills in its handle for the line device.
dwTSPIVersion
The TSPI version.
lpfnEventProc
A pointer to the LINEEVENT callback procedure supplied by TAPI that the service provider calls to report subsequent events on the line.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_ALLOCATED, LINEERR_OPERATIONUNAVAIL, LINEERR_NODRIVER, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

The service provider should reserve any non-sharable resources that are required to manage the line. However, any actions that can be postponed to lineMakeCall should be. It is a design assumption in TAPI that lineOpen is an "inexpensive" operation. For example, if the line is opened in monitor mode only, it should not be necessary for a COMM-port-based service provider to open the COMM port.

This procedure does not correspond directly to any procedure at the TAPI level, at which the functions of enabling device-specific extensions, selecting line characteristics, and setting media mode detection are included in the functionality defined by lineOpen. At the TSPI level, these additional capabilities are separated out into TSPI_lineNegotiateExtVersion, TSPI_lineSetDefaultMediaDetection and TSPI_lineConditionalMediaDetection.

See Also

LINE_CLOSE, LINEEVENT, TSPI_lineClose, TSPI_lineConditionalMediaDetection, TSPI_lineNegotiateExtVersion, TSPI_lineNegotiateTSPIVersion, TSPI_lineSetDefaultMediaDetection


TSPI_linePark

The TSPI_linePark function parks the specified call according to the specified park mode.

LONG TSPI_linePark(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  DWORD dwParkMode,
  LPCWSTR lpszDirAddress,
  LPVARSTRING lpNonDirAddress
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the call to be parked. The call state of hdCall can be connected.
dwParkMode
The park mode with which the call is to be parked. Only one of the following LINEPARKMODE_ flags can be set at a time:
LINEPARKMODE_DIRECTED
TAPI specifies the address at which the call is to be parked in lpszDirAddress.
LINEPARKMODE_NONDIRECTED
This operation reports to TAPI where the call has been parked in lpNonDirAddress.
lpszDirAddress
A pointer to NULL-terminated Unicode string that indicates the address where the call is to be parked when using directed park. The address is in dialable address format. This parameter is ignored for nondirected park.
lpNonDirAddress
A pointer to a structure of type VARSTRING. For nondirected park, the address where the call is parked is returned in this structure. This parameter is ignored for directed park. Within the VARSTRING structure, dwStringFormat must be set to STRINGFORMAT_ASCII (an ASCII string buffer containing a NULL-terminated string), and the terminating NULL is accounted for in the dwStringSize. If the memory pointed to by the lpNonDirAddress parameter is not large enough for the requested address, the TSPI_linePark function returns LINEERR_STRUCTURETOOSMALL.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALPARKMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESS, LINEERR_RESOURCEUNAVAIL, LINEERR_STRUCTURETOOSMALL.

Remarks

All members of the VARSTRING structure, except dwTotalSize, are filled in by the service provider. The dwTotalSize member is filled in by TAPI, and the service provider must not overwrite this value.

Under directed park, the client application (through TAPI) specifies the address at which it wants to park the call. Under nondirected park, the switch determines the address and provides this to TAPI. In either case, a parked call can be unparked by specifying this address.

The parked call typically enters the idle call state after it is successfully parked. The service provider reports the new state using a LINE_CALLSTATE message. A subsequent TSPI_lineUnpark creates a new, distinct call handle, regardless of whether TSPI_lineCloseCall has destroyed the old handle.

Some switches can remind the user after a call has been parked for some long amount of time. The service provider reports this to TAPI as an offering call with a call reason set to reminder (if this is known).

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINEPARKMODE_ Constants, TSPI_lineCloseCall, TSPI_lineUnpark, VARSTRING


TSPI_linePickup

The TSPI_linePickup function picks up a call alerting at the specified destination address and returns a call handle for the picked-up call. If invoked with NULL for the lpszDestAddress parameter, a group pickup is performed. If required by the device capabilities, lpszGroupID specifies the group identifier to which the alerting station belongs.

LONG TSPI_linePickup(
  DRV_REQUESTID dwRequestID,
  HDRVLINE hdLine,
  DWORD dwAddressID,
  HTAPICALL htCall,
  LPHDRVCALL lphdCall,
  LPCWSTR lpszDestAddress,
  LPCWSTR lpszGroupID
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdLine
The handle to the line on which a call is to be picked up.
dwAddressID
The address on hdLine at which the pickup is to be originated.
htCall
The TAPI handle to the new call. The service provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the call.
lphdCall
A pointer to an HDRVCALL representing the service provider's identifier for the call. The service provider must fill this location with its handle for the call before this procedure returns. This handle is ignored by TAPI if the function results in an error.
lpszDestAddress
A pointer to a NULL-terminated Unicode string that contains the address whose call is to be picked up. The address is standard link format.
lpszGroupID
A pointer to a NULL-terminated Unicode string containing the group identifier to which the alerting station belongs. This parameter is required on some switches to pick up calls outside of the current pickup group.

Note lpszGroupID can be specified by itself with a NULL pointer for lpszDestAddress. Alternatively, lpszGroupID can be specified in addition to lpszDestAddress, if required by the device. It can also be NULL itself.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALGROUPID, LINEERR_RESOURCEUNAVAIL.

Remarks

When a call has been picked up successfully, the service provider notifies TAPI with the LINE_CALLSTATE message about call state changes. The LINECALLINFO structure supplies information about the call that was picked up. It lists the reason for the call as pickup. This structure is available by calling TSPI_lineGetCallInfo.

The service provider sets LINEADDRCAPFLAGS_PICKUPCALLWAIT to TRUE in the LINEADDRESSCAPS structure if TSPI_linePickup can be used to pick up a call for which the user has audibly detected the call-waiting signal, but for which the provider is unable to perform the detection. This gives the user a mechanism to answer a waiting call even though the service provider was unable to detect the call-waiting signal. When TSPI_linePickup is being used to pick up a call-waiting call, both lpszDestAddress and lpszGroupID pointer parameters are NULL. The service provider creates a new call handle for the waiting call and passes that handle to the user in lphdCall. The dwAddressID parameter is most often zero (particularly in single-line residential cases).

Once TSPI_linePickup is used to pick up the second call, TSPI_lineSwapHold can be used to toggle between them. TSPI_lineDrop can be used to drop one (and toggle to the other), and so forth. If the user wants to drop the current call and pick up the second call, they call TSPI_lineDrop when they get the call-waiting beep, wait for the second call to ring, and then call TSPI_lineAnswer on the new call handle. The service provider sets the LINEADDRFEATURE_PICKUP flag in the dwAddressFeatures member in LINEADDRESSSTATUS to indicate when pickup is actually possible.

This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETION message reports success. In other words, it must not issue any LINEEVENT messages for the new call or include it in call counts in messages or status data structures for the line.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINEADDRESSCAPS, LINEADDRESSSTATUS, LINECALLINFO, LINECALLSTATUS, LINEEVENT, TSPI_lineAnswer, TSPI_lineDrop, TSPI_lineGetCallInfo, TSPI_lineGetCallStatus, TSPI_lineSwapHold


TSPI_linePrepareAddToConference

The TSPI_linePrepareAddToConference function prepares an existing conference call for the addition of another party. It creates a new, temporary consultation call. The new consultation call can be subsequently added to the conference call.

LONG TSPI_linePrepareAddToConference(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdConfCall,
  HTAPICALL htConsultCall,
  LPHDRVCALL lphdConsultCall,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdConfCall
The handle to a conference call. The call state of hdConfCall can be connected.
htConsultCall
The TAPI handle to the new, temporary consultation call. The service provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the new call. The call state of hdAddCall is not applicable.
lphdConsultCall
A pointer to an HDRVCALL representing the service provider's identifier for the new, temporary consultation call. The service provider must fill this location with its handle for the new call before this procedure returns. This handle is invalid if the function results in an error.
lpCallParams
A pointer to call parameters to be used when establishing the consultation call. This parameter is set to NULL if no special call setup parameters are desired.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_CALLUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_CONFERENCEFULL, LINEERR_INVALRATE, LINEERR_INUSE, LINEERR_NOMEM, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALBEARERMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLPARAMS, LINEERR_RATEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCONFCALLHANDLE, LINEERR_USERUSERINFOTOOBIG.

Remarks

The service provider returns LINEERR_INVALLINESTATE if the line is currently not in a state in which this operation can be performed. The service provider must indicate a list of currently valid operations in the dwLineFeatures member (of the type LINEFEATURE) in the LINEDEVSTATUS structure.

The service provider returns LINEERR_INVALCALLSTATE if the conference call is not in a valid state for the requested operation.

This function places an existing conference call in the onHoldPendingConference state and creates a consultation call that can be added later to the existing conference call with TSPI_lineAddToConference.

The consultation call can be canceled using TSPI_lineDrop. It may also be possible for TAPI to swap between the consultation call and the held conference call with TSPI_lineSwapHold. The service provider initially does media monitoring on the new call for at least the set of media modes that were monitored for on the line.

This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETION message reports success. In other words, it must not issue any LINEEVENT messages for the new call or include it in call counts in messages or status data structures for the line.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINEDEVSTATUS, LINEEVENT, TSPI_lineAddToConference, TSPI_lineDial, TSPI_lineDrop, TSPI_lineRemoveFromConference, TSPI_lineSetupConference, TSPI_lineSwapHold


TSPI_lineRedirect

The TSPI_lineRedirect function redirects the specified offering call to the specified destination address.

LONG TSPI_lineRedirect(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPCWSTR lpszDestAddress,
  DWORD dwCountryCode
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the call to be redirected. The call state of hdCall can be offering.
lpszDestAddress
A pointer to the destination address. This follows the standard link format.
dwCountryCode
The country code of the party the call is redirected to. If a value of 0 is specified, a default is used by the implementation. This parameter is not validated by TAPI when this function is called.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCOUNTRYCODE, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESS, LINEERR_RESOURCEUNAVAIL.

Remarks

The service provider does not redirect the call if it returns LINEERR_INVALADDRESS.

When this function is invoked, the service provider deflects the offering call to another address without first answering the call. Call redirect differs from call forwarding in that call forwarding is performed by the switch without the involvement of the called station; redirection can be done on a call-by-call basis by a client application, for example driven by caller ID information. It differs from call transfer in that transferring a call requires that the call first be answered.

After a call is successfully redirected, the call typically transitions to idle. The service provider indicates the new state using a LINE_CALLSTATE message.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, TSPI_lineAccept, TSPI_lineDrop, TSPI_lineGetDevCaps


TSPI_lineReleaseUserUserInfo

The TSPI_lineReleaseUserUserInfo function informs the service provider that the user-user information contained in the LINECALLINFO structure has been processed, and that subsequently received user-user information can now be written into that structure. The service provider sends a LINE_CALLINFO message indicating LINECALLINFOSTATE_USERUSERINFO when new information is available.

LONG TSPI_lineReleaseUserUserInfo(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The service provider's handle to the call for which user-user information is to be released. The call state of hdCall can be any.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

The TSPI_lineReleaseUserUserInfo function permits control of the flow of incoming user-user information on an ISDN connection. When a new, complete user-user information message is received, the service provider informs TAPI using a LINE_CALLINFO message (specifying LINECALLINFOSTATE_USERUSERINFO). The user-user information and other fields in LINECALLINFO can be examined by multiple calls to TSPI_lineGetCallInfo. The service provider must not overwrite previous user-user information in LINECALLINFO with newer information until after TSPI_lineReleaseUserUserInfo has been called. The service provider must buffer subsequently received user-user information until the previous information is released. Any remaining buffered information can be discarded when TSPI_lineCloseCall is invoked.

If this function is invoked while there is no user-user information in LINECALLINFO, the service provider should nevertheless return an indication of success.

For backward compatibility, TAPI automatically returns LINEERR_OPERATIONUNAVAIL if this function is invoked for a call on a line under the control of a service provider that does not export the function.

See Also

ASYNC_COMPLETION, LINE_CALLINFO, LINECALLINFO, TSPI_lineGetCallInfo


TSPI_lineRemoveFromConference

The TSPI_lineRemoveFromConference function removes the specified call from the conference call to which it currently belongs. The remaining calls in the conference call are unaffected.

LONG TSPI_lineRemoveFromConference(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the call to be removed from the conference. The call state of hdCall can be conferenced.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

This operation removes a party that currently belongs to a conference call. After the call has been successfully removed, it may be possible to further manipulate it using its handle. The availability of this operation and its result are likely to be limited in many implementations. For example, in many implementations, only the most recently added party can be removed from a conference, and the removed call may be automatically dropped (becomes idle). The service provider indicates its capabilities in LINEDEVCAPS with regard to the available effects of removing a call from a conference.

If the removal of a participant from a conference is supported, the service provider must indicate in the dwRemoveFromConfState member in LINEADDRESSCAPS the call state to which the call transitions after it is removed from the conference.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINEADDRESSCAPS, LINEDEVCAPS, TSPI_lineAddToConference, TSPI_lineGetDevCaps, TSPI_lineSetupConference


TSPI_lineSecureCall

The TSPI_lineSecureCall function secures the call from any interruptions or interference that can affect the call's media stream.

LONG TSPI_lineSecureCall(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the call to be secured. The call state of hdCall can be any state except idle.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

A call can be secured to avoid interference. For example, in an analog environment, call waiting tones can destroy a fax or modem session on the original call. TSPI_lineSecureCall allows an existing call to be secured, TSPI_lineMakeCall provides the option to secure the call from the time of call setup. The securing of a call remains in effect for the duration of the call.

See Also

ASYNC_COMPLETION, TSPI_lineMakeCall


TSPI_lineSelectExtVersion

The TSPI_lineSelectExtVersion function selects the indicated extension version for the indicated line device. Subsequent requests operate according to that extension version.

LONG TSPI_lineSelectExtVersion(
  HDRVLINE hdLine,
  DWORD dwExtVersion
);

Parameters

hdLine
The handle to the line for which an extension version is to be selected.
dwExtVersion
The extension version to be selected. This version number has been negotiated using TSPI_lineNegotiateExtVersion. The most significant WORD is the major version number and the least significant WORD is the minor version number. Calling this function with a dwExtVersion of zero cancels the current selection.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_OPERATIONUNAVAIL.

Remarks

The service provider selects the indicated extension version. Although the indicated version number may have been successfully negotiated, a different extension version may have been selected in the interim, in which case this function fails (returning LINEERR_INCOMPATIBLEEXTVERSION).

Subsequent operations on the line after an extension version has been selected behave according to that extension version. Subsequent attempts to negotiate the extension version report strictly the selected version or 0 (if the requested range does not include the selected version). Calling this procedure with the special extension version 0 cancels the current selection. The device becomes once again capable of supporting its full range of extension version numbers.

This function has no direct correspondence at the TAPI level, where selecting an extension version is bundled with the other functions of lineOpen. The TSPI_lineSelectExtVersion function is typically called in two situations: (1) An application requested to open a line, the resulting change of media mode monitoring was successful, the application requested that a particular extension version be used, and no extension version was currently selected. (2) The last application using a particular extension version closed the line, and the extension version selection can be canceled.

See Also

TSPI_lineNegotiateExtVersion


TSPI_lineSendUserUserInfo

The TSPI_lineSendUserUserInfo function sends user-user information to the remote party on the specified call.

LONG TSPI_lineSendUserUserInfo(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPCWSTR lpsUserUserInfo,
  DWORD dwSize
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the call on which to send user-user information. The call state of hdCall can be connected, offering, accepted, or ringback.
lpsUserUserInfo
A pointer to a string containing user-user information to be sent to the remote party. User-user information is only sent if supported by the underlying network (see LINEDEVCAPS).
dwSize
The size in bytes of the user-user information in lpsUserUserInfo.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALCALLSTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_USERUSERINFOTOOBIG, LINEERR_OPERATIONUNAVAIL.

Remarks

This function can be used to send user-user information at any time during a connected call. If the size of the specified information to be sent is larger than what can fit into a single network message (as in ISDN), the service provider is responsible for breaking the information up into a sequence of chained network messages (using "more data").

User-user information can also be sent as part of call accept, call reject, call redirect, and when making calls. User-user information can also be received. The received information is reported in the call's LINECALLINFO structure. Whenever user-user information arrives after call offering or prior to call disconnect, a LINE_CALLINFO message with a UserUserInfo parameter notifies TAPI that user-user information in the call-information record has changed. If multiple network messages are chained, the information is assembled by the service provider and a single message is sent to TAPI.

See Also

LINE_CALLINFO, LINECALLINFO, TSPI_lineAccept, TSPI_lineDrop, TSPI_lineGetCallInfo, TSPI_lineMakeCall, TSPI_lineRedirect


TSPI_lineSetAppSpecific

The TSPI_lineSetAppSpecific function sets the application-specific field of the specified call's LINECALLINFO structure.

LONG TSPI_lineSetAppSpecific(
  HDRVCALL hdCall,
  DWORD dwAppSpecific
);

Parameters

hdCall
The handle to the call whose application-specific field is to be set. The call state of hdCall can be any state.
dwAppSpecific
The new content of the dwAppSpecific member for the call's LINECALLINFO structure. This value is uninterpreted by the service provider. This parameter is not validated by TAPI when this function is called.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_OPERATIONUNAVAIL.

Remarks

The application-specific field in the LINECALLINFO data structure that exists for each call is uninterpreted by the Telephony API or any of its service providers. Its usage is entirely defined by the applications. The field can be read from the LINECALLINFO record returned by TSPI_lineGetCallInfo. However, TSPI_lineSetAppSpecific must be used to set the field so that changes become visible to other applications. When this field is changed, the service provider sends a LINE_CALLINFO message with an indication that the AppSpecific field has changed.

See Also

LINE_CALLINFO, LINECALLINFO, TSPI_lineGetCallInfo


TSPI_lineSetCallData

The TSPI_lineSetCallData function service provider stores the indicated call data with its information related to the call, and subsequently delivers it whenever TSPI_lineGetCallInfo is called. The service provider sends a LINE_CALLINFO message indicating LINECALLINFOSTATE_CALLDATA to show that the call data has changed. Depending on the service provider implementation, the call data can be propagated to all entities having handles to the call, including those on other machines (through the server), and can travel with the call when it is transferred.

LONG TSPIAPI TSPI_lineSetCallData(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPVOID lpCallData,
  DWORD dwSize
);

Parameters

dwRequestID
Identifier for reporting asynchronous completion information.
hdCall
The service provider's handle to the call.
lpCallData
Address of the data to be copied to the CallData field in LINECALLINFO, replacing any existing data.
dwSize
Number of bytes of data to be copied. A value of 0 causes any existing data to be removed.

Return Values

Returns dwRequestID if the asynchronous operation starts; otherwise, one of these negative error values:

LINEERR_INVALCALLSTATE, LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_RESOURCEUNAVAIL.

See Also

LINE_CALLINFO, LINECALLINFO, TSPI_lineGetCallInfo


TSPI_lineSetCallParams

The TSPI_lineSetCallParams function sets certain parameters for an existing call.

LONG TSPI_lineSetCallParams(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  DWORD dwBearerMode,
  DWORD dwMinRate,
  DWORD dwMaxRate,
  LPLINEDIALPARAMS const lpDialParams
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the call whose parameters are to be changed. The call state can be any state except idle and disconnected.
dwBearerMode
The new bearer mode for the call. The dwBearerMode parameter can have only one of the following LINEBEARERMODE_flags set:
LINEBEARERMODE_VOICE
A regular 3.1kHz analog voice grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.
LINEBEARERMODE_SPEECH
Corresponds to G.711 speech transmission on the call. The network can use processing techniques such as analog transmission, echo cancellation and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.
LINEBEARERMODE_MULTIUSE
The multiuse mode defined by ISDN.
LINEBEARERMODE_DATA
The unrestricted data transfer on the call. The data rate is specified separately.
LINEBEARERMODE_ALTSPEECHDATA
The alternate transfer of speech or unrestricted data on the same call (ISDN).
LINEBEARERMODE_NONCALLSIGNALING
Corresponds to a non-call-associated signaling connection from the application to the service provider or switch (treated as a media stream by TAPI).
LINEBEARERMODE_PASSTHROUGH
When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 comm functions, for the purpose of configuring or using special features not otherwise supported by the service provider.
dwMinRate
A lower bound for the call's new data rate. TAPI can accept a new rate as low as this one. TAPI does not validate this parameter when this function is called.
dwMaxRate
An upper bound for the call's new data rate. This is the maximum data rate TAPI would like. Equal values for dwMinRate and dwMaxRate indicate that an exact data rate is required. TAPI does not validate this parameter when this function is called.
lpDialParams
A pointer to the new dial parameters for the call, of type LINEDIALPARAMS. If this parameter is NULL, it indicates that the call's current dialing parameters are to be used.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_RATEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_NOMEM, LINEERR_INVALBEARERMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALRATE, LINEERR_RESOURCEUNAVAIL, LINEERR_BEARERMODEUNAVAIL.

Remarks

This operation is used to change the parameters of an existing call. Examples of its usage include changing the bearer mode and/or the data rate of an existing call.

See Also

ASYNC_COMPLETION, LINECALLPARAMS, LINEDIALPARAMS, TSPI_lineMakeCall


TSPI_lineSetCallQualityOfService

The TSPI_lineSetCallQualityOfService function service provider attempts to renegotiate the QOS on the call with the switch If the desired QOS is not available, then the function fails, but the call continues with the previous QOS. If the function succeeds, the new QOS information is stored in LINECALLINFO; a LINECALLINFOSTATE_QOS message is sent by the service provider to indicate the updated values.

LONG TSPIAPI TSPI_lineSetCallQualityOfService(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  LPVOID lpSendingFlowspec,
  DWORD dwSendingFlowspecSize,
  LPVOID lpReceivingFlowspec,
  DWORD dwReceivingFlowspecSize
);

Parameters

dwRequestID
Identifier for reporting asynchronous function results.
hdCall
The service provider's handle to the call.
lpSendingFlowspec
Pointer to memory containing a WinSock2 FLOWSPEC structure followed by provider-specific data. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory in the application process, because TAPI does not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the service provider.
dwSendingFlowspecSize
The total size in bytes of the FLOWSPEC and accompanying provider-specific data, equivalent to what would have been stored in SendingFlowspec.len in a WinSock2 QOS structure.
lpReceivingFlowspec
Pointer to memory containing a WinSock2 FLOWSPEC structure followed by provider-specific data. The provider-specific portion following the FLOWSPEC structure must not contain pointers to other blocks of memory in the application process, because TAPI does not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the service provider.
dwReceivingFlowspecSize
The total size in bytes of the FLOWSPEC and accompanying provider-specific data, equivalent to what would have been stored in ReceivingFlowspec.len in a WinSock2 QOS structure.

Return Values

Returns dwRequestID if the asynchronous operation starts; otherwise, the function returns one of these negative error values:

LINEERR_INVALCALLSTATE, LINEERR_INVALRATE, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_RATEUNAVAIL, LINEERR_RESOURCEUNAVAIL.

See Also

LINECALLINFO


TSPI_lineSetCallTreatment

The TSPI_lineSetCallTreatment function service provider stores the indicated dwCallTreatment in LINECALLINFO, and sends a LINE_CALLINFO message to indicate the updated information. If the call is currently in a state where the call treatment is relevant, the new treatment goes into effect at once; otherwise, it goes into effect the next time the call enters a relevant state.

LONG TSPIAPI TSPI_lineSetCallTreatment(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  DWORD dwCallTreatment
);

Parameters

dwRequestID
Identifier for reporting asynchronous function results.
hdCall
The service provider's handle to the call.
dwCallTreatment
One of the call treatment identifiers supported on the address on which the call appears.

Return Values

Returns dwRequestID if the asynchronous operation starts; otherwise, one of these negative error values:

LINEERR_INVALCALLSTATE, LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_RESOURCEUNAVAIL.

See Also

LINE_CALLINFO, LINECALLINFO


TSPI_lineSetCurrentLocation

This TSPI_lineSetCurrentLocation function is called by TAPI whenever the address translation location is changed by the user (in the Dialing Propertiesdialog box) or an application (using the lineSetCurrentLocation function). Service providers that store parameters specific to a location (for example, touch-tone sequences to invoke particular PBX functions) use the location to select the set of parameters applicable to the new location.

LONG TSPIAPI TSPI_lineSetCurrentLocation(
  DWORD dwLocation
);

Parameters

dwLocation
The permanent location identifier of the selected location.

Return Values

Returns zero if the request succeeds or an error number if an error occurs. Possible return values are:

LINEERR_NOMEM and LINEERR_OPERATIONFAILED.

Remarks

Service providers that store sets of parameters based on the user's current location should identify those sets by the permanent location identifier of the location.

If the service provider does not implement specific parameters by location, this function can be omitted.

If the value passed in to the service provider by this function is not recognized by the service provider (for example, because no location-specific parameters have yet been set for the specified location), the service provider uses a default set of parameters.

TAPI ignores the value returned by the service provider for this function; it is returned for debugging purposes only.

The service provider can synchronize its stored location-specific parameters with the locations stored by TAPI whenever the TSPI_providerConfig or TSPI_lineConfigDialog function is called, by using the lineGetTranslateCaps function to obtain a table of current locations. Newly defined locations and removed locations can be detected at this time, and appropriate adjustments made to the service provider's stored location parameters (including prompting the user to make settings for new locations).

For backward compatibility, if the service provider does not export this function, TAPI does not call it, and no ill effects result.

See Also

TSPI_lineConfigDialog, TSPI_providerConfig


TSPI_lineSetDefaultMediaDetection

The TSPI_lineSetDefaultMediaDetection procedure tells the service provider the new set of media modes to detect for the indicated line (replacing any previous set). It also sets the initial set of media modes that should be monitored for on subsequent calls (inbound or outbound) on this line.

LONG TSPI_lineSetDefaultMediaDetection(
  HDRVLINE hdLine,
  DWORD dwMediaModes
);

Parameters

hdLine
The handle to the line to have media monitoring set.
dwMediaModes
The media mode(s) of interest to TAPI. This parameter uses the following LINEMEDIAMODE_ constants:
LINEMEDIAMODE_UNKNOWN
TAPI can handle calls of unknown media type (unclassified calls).
LINEMEDIAMODE_INTERACTIVEVOICE
TAPI can handle calls of the interactive voice media type. That is, it manages live voice calls.
LINEMEDIAMODE_AUTOMATEDVOICE
TAPI can handle calls in which there is voice data managed by an automated application. In cases where the service provider does not distinguish between automated or interactive voice, this is treated the same as interactive voice.
LINEMEDIAMODE_DATAMODEM
TAPI can handle calls with the data modem media mode.
LINEMEDIAMODE_G3FAX
TAPI can handle calls of the group 3 fax media type.
LINEMEDIAMODE_TDD
TAPI can handle calls with the TDD (Telephony Devices for the Deaf) media mode.
LINEMEDIAMODE_G4FAX
TAPI can handle calls of the group 4 fax media type.
LINEMEDIAMODE_DIGITALDATA
TAPI can handle calls of the digital data media type.
LINEMEDIAMODE_TELETEX
TAPI can handle calls with the teletex media mode.
LINEMEDIAMODE_VIDEOTEX
TAPI can handle calls with the videotex media mode.
LINEMEDIAMODE_TELEX
TAPI can handle calls with the telex media mode.
LINEMEDIAMODE_MIXED
TAPI can handle calls with the ISDN mixed media mode.
LINEMEDIAMODE_ADSI
TAPI can handle calls with the ADSI (Analog Display Services Interface) media mode.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL.

Remarks

TAPI typically calls this function to update the set of detected media modes for the line to the union of all modes selected by all outstanding lineOpens whenever a line is Opened or Closed at the TAPI level. A lineOpen call attempt is rejected if media detection is rejected. A single call to this procedure is typically the result of a lineOpen call that does not specify the device identifier LINEMAPPER. The device identifier LINEMAPPER is never used at the TSPI level.

TAPI must compute the union of media modes desired by all clients and pass the result to this function. The service provider uses the set passed to this function by TAPI. TAPI ensures that the dwMediaModes parameter has at least one bit set and that no reserved bits are set. The service provider must perform any further validity checks on the media modes, such as checking whether any media modes are indeed supported by the service provider. The union of all media modes can be the value 0 if the applications that have the line open are all either monitors or not interested in handling incoming calls.

There is no directly corresponding function at the TAPI level. This procedure corresponds to the "request media modes" implied for the specific line by the lineOpen procedure when it is called with the specific device identifier (other than LINEMAPPER).

See Also

LINECALLPARAMS, LINEMEDIAMODE_ Constants, TSPI_lineClose


TSPI_lineSetDevConfig

The TSPI_lineSetDevConfig function restores the configuration of a device associated one-to-one with the line device from an "" data structure previously obtained using TSPI_lineGetDevConfig. The contents of this data structure are specific to the line [service provider] and device class.

LONG TSPI_lineSetDevConfig(
  DWORD dwDeviceID,
  LPVOID const lpDeviceConfig,
  DWORD dwSize,
  LPCWSTR lpszDeviceClass
);

Parameters

dwDeviceID
The line device to be configured.
lpDeviceConfig
A pointer to the configuration data structure that is returned in the variable portion of the VARSTRING structure by TSPI_lineGetDevConfig.
dwSize
The number of bytes in the structure pointed to by lpDeviceConfig. This value is returned in the dwStringSize member in the VARSTRING structure returned by TSPI_lineGetDevConfig.
lpszDeviceClass
A pointer to a NULL-terminated Unicode string that specifies the device class of the device whose configuration is to be restored. Valid device class strings are the same as those specified for the TSPI_lineGetID function when it is applied to a "line" device (that is, when dwSelect has the value LINECALLSELECT_LINE).

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are:

LINEERR_INVALDEVICECLASS, LINEERR_NOMEM, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPARAM, LINEERR_OPERATIONFAILED, LINEERR_INVALLINESTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NODRIVER.

Remarks

The call state is device specific.

The service provider returns LINEERR_INVALPARAM if the information contained in the structure pointed to by lpDeviceConfig is not valid for this device.

The service provider returns LINEERR_INVALLINESTATE if the device configuration cannot be changed in the current line state. The line may be in use by another application.

This function can be used to restore the configuration of a device associated one-to-one with the line device from a data structure previously retrieved from the service provider using the TSPI_lineGetDevConfig function. The lpszDeviceClass parameter selects which of among possibly several different classes of devices is to have its configuration restored. The set of supported classes is restricted to those whose devices correspond one-to-one with the line device. For more information about common device classes, see TSPI Device Classes.

A service provider typically allows the tapi/line device class under this function. It restores parameters that have "line" scope, such as the list of addresses in this line and the list of physical hardware devices such as COMM ports corresponding to the addresses or the maximum number of concurrent calls (if configurable).

In general, this function does NOT allow media-related device classes such as mci waveaudio, low level wave, or datamodem device classes, because these usually apply to a particular call or a particular address. Because there can be more than one of these per line device, the identification of the particular call or address simply by the line device identifier parameter in this function is ambiguous. An exception can be made for call-specific or address-specific device classes in cases where there is class configuration information that applies to the entire line device scope, such as initial defaults.

There are several reasons why exceptional support for call-specific and address-specific device classes is of only limited value under this function. First, because these classes can be ambiguous on multiple-address, multiple-call service providers, only a subset of service providers support them. Application programs are not likely to add a device-specific dependency on the inclusion of these classes in this function. Second, as higher-level media classes emerge that implement high-level protocols such as dial-in file system access in terms of low-level transport APIs, configuration for these classes tends toward instance scope instead of class scope. The high-level media API has to supply its own functions to configure call-specific or address-specific instances.

Whatever sort of devices and device classes this function supports, it can potentially affect two kinds of configuration information: permanent and temporary. Permanent information survives across different "opens" of the line, and even across different "inits" of the service provider itself. Temporary information survives only within a unique "open" of the line. When the line is closed, any such temporary information that has been set or retrieved through TSPI_lineGetDevConfig can revert to default or undefined values. The caller can reliably retrieve any temporary configuration only by a sequence such as TSPI_lineOpen, TSPI_lineConfigDialog, TSPI_lineGetDevConfig. The caller can reliably set temporary configuration information retrieved by such a sequence through a sequence such as TSPI_lineOpen, TSPI_lineSetDevConfig. The temporary part of configuration remains stable only until the next TSPI_lineConfigDialog, TSPI_lineSetDevConfig, or TSPI_lineClose. The service provider must take care of storing any permanent part of the configuration, typically in an .ini file, and reloading it whenever the service provider is initialized.

The exact format of the data contained within the structure passed to this function is specific to the line and device class API, is undocumented, and is undefined. The structure passed to this function cannot be directly accessed or manipulated by the application, but can only be stored intact and later used from a previous TSPI_lineGetDevConfig to obtain the settings. The structure also cannot necessarily be passed to other devices, even of the same device class (although this may work in some instances, it is not guaranteed). A service provider should check this data structure for consistency to guard against failures due to a client application passing incompatible information.

Note Some service providers may permit the configuration to be set while a device is in use, and others may not.

See Also

TSPI_lineClose, TSPI_lineConfigDialog, TSPI_lineGetDevConfig, TSPI_lineGetID, TSPI_lineOpen, VARSTRING


TSPI_lineSetLineDevStatus

The TSPI_lineSetLineDevStatus service provider sets the device status as indicated, sending appropriate LINE_LINEDEVSTATE messages to indicate the new status.

LONG TSPIAPI TSPI_lineSetLineDevStatus(
  DRV_REQUESTID dwRequestID,
  HDRVLINE hdLine,
  DWORD dwStatusToChange,
  DWORD fStatus
);

Parameters

dwRequestID
Identifier for reporting asynchronous function results.
hdLine
The service provider's handle to the line device.
dwStatusToChange
One or more of the LINEDEVSTATUSFLAGS_ values.
fStatus
TRUE (-1) to turn on the indicated status bit(s), FALSE (0) to turn off.

Return Values

Returns dwRequestID if the asynchronous operation starts; otherwise, the function returns one of these negative error values:

LINEERR_INVALLINESTATE, LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_RESOURCEUNAVAIL.

See Also

LINE_LINEDEVSTATE


TSPI_lineSetMediaControl

The TSPI_lineSetMediaControl function enables and disables control actions on the media stream associated with the specified line, address, or call. Media control actions can be triggered by the detection of specified digits, media modes, custom tones, and call states. The new specified media controls replace all the ones that were in effect for this line, address, or call prior to this request.

LONG TSPI_lineSetMediaControl(
  HDRVLINE hdLine,
  DWORD dwAddressID,
  HDRVCALL hdCall,
  DWORD dwSelect,
  LPLINEMEDIACONTROLDIGIT const lpDigitList,
  DWORD dwDigitNumEntries,
  LPLINEMEDIACONTROLMEDIA const lpMediaList,
  DWORD dwMediaNumEntries,
  LPLINEMEDIACONTROLTONE const lpToneList,
  DWORD dwToneNumEntries,
  LPLINEMEDIACONTROLCALLSTATE const lpCallStateList,
  DWORD dwCallStateNumEntries
);

Parameters

hdLine
The handle to a line.
dwAddressID
An address on the given open line device. TAPI does not validate this parameter when this function is called.
hdCall
The handle to a call. The call state of hdCall can be any state.
dwSelect
Specifies whether media control is requested is associated with a single call, is the default for all calls on an address, or is the default for all calls on a line. This parameter uses the following LINECALLSELECT_ constants:
LINECALLSELECT_LINE
Select the specified line device. The hdLine parameter must be a valid line handle; hdCall and dwAddressID must be ignored.
LINECALLSELECT_ADDRESS
Select the specified address on the line. Both hdLine and dwAddressID must be valid; hdCall must be ignored.
LINECALLSELECT_CALL
Select the specified call. hdCall must be valid; hdLine and dwAddressID must be ignored.
lpDigitList
A pointer to the array that contains the digits that are to trigger media control actions, of type LINEMEDIACONTROLDIGIT. Each time a digit listed in the digit list is detected, the specified media control action is carried out on the call's media stream.

Valid digits for pulse mode are '0' through '9'. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.

dwDigitNumEntries
The number of entries in the lpDigitList. TAPI does not validate this parameter when this function is called.
lpMediaList
A pointer to an array with entries of type LINEMEDIACONTROLMEDIA. The array has dwMediaNumEntries entries. Each entry contains a media mode to be monitored, media-type specific information (such as duration), and a media control field. If a media mode in the list is detected, the corresponding media control action is performed on the call's media stream.
dwMediaNumEntries
The number of entries in lpMediaList. TAPI does not validate this parameter when this function is called.
lpToneList
A pointer to an array with entries of type LINEMEDIACONTROLTONE. The array has dwToneNumEntries entries. Each entry contains a description of a tone to be monitored, duration of the tone, and a media control field. If a tone in the list is detected, the corresponding media control action is performed on the call's media stream.
dwToneNumEntries
The number of entries in lpToneList. TAPI does not validate this parameter when this function is called.
lpCallStateList
A pointer to an array with entries of type LINEMEDIACONTROLCALLSTATE. The array has dwCallStateNumEntries entries. Each entry contains a call state and a media control action.
dwCallStateNumEntries
The number of entries in lpCallStateList. TAPI does not validate this parameter when this function is called.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALADDRESSID, LINEERR_INVALPOINTER, LINEERR_INVALCALLHANDLE, LINEERR_INVALTONELIST, LINEERR_INVALCALLSELECT, LINEERR_NOMEM, LINEERR_INVALCALLSTATELIST, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITLIST, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALMEDIALIST.

Remarks

This function returns zero (success) when media control is correctly initiated, not when any media control takes effect. Media control in progress is changed or is canceled when this function is called again with either different parameters or NULLs.

Only a single media control request can be outstanding on a call at one time. A request replaces any that may be outstanding.

Depending on the service provider and other activities that compete for such resources, the amount of simultaneous detections that can be made can vary over time. If service provider resources are overcommitted, it returns LINEERR_RESOURCEUNAVAIL.

Whether or not media control is supported by the service provider is a device capability indicated in LINEDEVCAPS.

Each time TSPI_lineSetMediaControl is called, the new request overrides any media control currently in effect. If one or more of the parameters lpDigitList, lpMediaList, lpToneList, and lpCallStateList are NULL, the corresponding digit, media mode, tone, or call state-triggered media control is disabled. To modify just a portion of the media control parameters while leaving the remaining settings in effect, the application should invoke TSPI_lineSetMediaControl supplying the previous parameters for those potions that must remain in effect, and new parameters for those parts that are to be modified.

See Also

LINEDEVCAPS, LINEMEDIACONTROLCALLSTATE, LINEMEDIACONTROLDIGIT, LINEMEDIACONTROLMEDIA, LINEMEDIACONTROLTONE, LINEDIGITMODE_ Constants, LINEMEDIAMODE_ Constants, TSPI_lineGetDevCaps


TSPI_lineSetMediaMode

The TSPI_lineSetMediaMode function changes the call's media as stored in the call's LINECALLINFO structure.

LONG TSPI_lineSetMediaMode(
  HDRVCALL hdCall,
  DWORD dwMediaMode
);

Parameters

hdCall
The handle to the call undergoing a change in media mode. The call state of hdCall can be any state.
dwMediaMode
The new media mode(s) for the call. As long as the LINEMEDIAMODE_UNKNOWN media mode flag is set, multiple other media mode flags can be set as well. This is used to identify a call's media mode as not fully determined, but narrowed down to one of just a small set of specified media modes. If the LINEMEDIAMODE_UNKNOWN flag is not set, only a single media mode can be specified. LINEMEDIAMODE_ constant values are:
LINEMEDIAMODE_UNKNOWN
The anticipated media type is not fully classified.
LINEMEDIAMODE_INTERACTIVEVOICE
The anticipated media type is interactive voice media mode, namely live conversations.
LINEMEDIAMODE_AUTOMATEDVOICE
TAPI can handle calls in which there is voice data, but the voice is handled by an automated application. Most service providers cannot distinguish between automated and interactive voice. In such a case any request for voice or detection of voice is treated as interactive voice.
LINEMEDIAMODE_DATAMODEM
The anticipated media type is data modem media mode.
LINEMEDIAMODE_G3FAX
The anticipated media type is group 3 fax media mode.
LINEMEDIAMODE_TDD
The anticipated media type is TDD (Telephony Devices for the Deaf) media mode.
LINEMEDIAMODE_G4FAX
The anticipated media type is group 4 fax media mode.
LINEMEDIAMODE_DIGITALDATA
The anticipated media type is digital data calls.
LINEMEDIAMODE_TELETEX
The anticipated media type is teletex media mode.
LINEMEDIAMODE_VIDEOTEX
The anticipated media type is videotex media mode.
LINEMEDIAMODE_TELEX
The anticipated media type is telex media mode.
LINEMEDIAMODE_MIXED
The anticipated media type is ISDN mixed media mode.
LINEMEDIAMODE_ADSI
The anticipated media type is ADSI (Analog Display Services Interface) media mode.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

Other than changing the call's media as stored in the call's LINECALLINFO structure, this procedure is simply advisory in the sense that it indicates an expected media change that is about to occur, rather than forcing a specific change to the call. Typical usage is to set a call's media mode to a specific known media mode, or to exclude possible media modes as long as the call's media mode is not fully known (the UNKNOWN media mode flag is set).

TAPI makes the following guarantees regarding the passed media mode: (1) there is at least one bit set, (2) there are no reserved bits set, and (3) if more than one bit is set, "Unknown" is also set. The service provider must perform any further validity checks on the media modes, such as checking whether any media modes are indeed supported by the service provider.

See Also

LINECALLINFO, LINEMEDIAMODE_ Constants, TSPI_lineGetCallInfo


TSPI_lineSetStatusMessages

The TSPI_lineSetStatusMessages function enables TAPI to specify which notification messages the service provider should generate for events related to status changes for the specified line or any of its addresses.

LONG TSPI_lineSetStatusMessages(
  HDRVLINE hdLine,
  DWORD dwLineStates
);

Parameters

hdLine
The handle to the line device for which the new filter is to be set.
dwLineStates
A bit array that identifies for which line device status changes a message is to be sent to TAPI. This parameter uses the following LINEDEVSTATE_. constants:
LINEDEVSTATE_OTHER
Device-status items other than those listed below have changed.
LINEDEVSTATE_RINGING
The switch tells the line to alert the user. This should be sent repeatedly in a LINE_LINEDEVSTATE message, once for each ring cycle. On a POTS device, the service provider can send the message whenever the central office sends ring voltage. On digital devices such as ISDN, the service provider may need to synthesize the repetition of the message if the switch generates only one ring request. Each repetition of the message should show the ring count increasing, so that toll save functions work properly.
LINEDEVSTATE_CONNECTED
The line was previously disconnected and is now connected to the service provider.
LINEDEVSTATE_DISCONNECTED
This line was previously connected and is now disconnected from the service provider.
LINEDEVSTATE_MSGWAITON
The "message waiting" indicator is turned on.
LINEDEVSTATE_MSGWAITOFF
The "message waiting" indicator is turned off.
LINEDEVSTATE_INSERVICE
The line is connected to the service provider. This happens when the service provider is first activated, or when the line wire is physically plugged in and in service at the switch while the service provider is active.
LINEDEVSTATE_OUTOFSERVICE
The line is out of service at the switch or is physically disconnected. The API cannot be used to operate on the line device.
LINEDEVSTATE_MAINTENANCE
Maintenance is being performed on the line at the switch. The service provider cannot be used to operate on the line device.
LINEDEVSTATE_NUMCALLS
The number of calls on the line device has changed.
LINEDEVSTATE_NUMCOMPLETIONS
The number of outstanding call completions on the line device has changed.
LINEDEVSTATE_TERMINALS
The terminal settings have changed.
LINEDEVSTATE_ROAMMODE
The roaming mode of the line device has changed.
LINEDEVSTATE_BATTERY
The battery level has changed significantly (cellular).
LINEDEVSTATE_SIGNAL
The signal level has changed significantly (cellular).
LINEDEVSTATE_DEVSPECIFIC
The line's device-specific information has changed.
LINEDEVSTATE_REINIT
Items have changed in the configuration of line devices. To become aware of these changes (as with the appearance of new line devices) TAPI notifies all its client applications to reinitialize their use of the API. A service provider should initiate such a sequence only in extreme cases that cannot be handled through the normal configuration-change notification mechanism described in the Overview section. The LINEDEVSTATE_REINIT message is never masked. REINIT messages should always be sent when appropriate, regardless of the setting of this flag. The setting of the REINIT flag is simply ignored and generates no error.
LINEDEVSTATE_LOCK
The locked status of the line device has changed.
LINEDEVSTATE_REMOVED
The device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A LINE_LINEDEVSTATE message with this value is normally immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated this or a subsequent API version; applications negotiating a previous API version do not receive any notification.
DWORD dwAddressStates
A bit array that identifies for which address status changes a message is to be sent to TAPI. This parameter uses the following LINEADDRESSSTATE_ constants:
LINEADDRESSSTATE_OTHER
Address-status items other than those listed below have changed.
LINEADDRESSSTATE_DEVSPECIFIC
The device-specific item of the address status has changed.
LINEADDRESSSTATE_INUSEZERO
The address has changed to idle (it is now in use by zero stations).
LINEADDRESSSTATE_INUSEONE
The address has changed from being idle or from being in use by many bridged stations to being in use by just one station.
LINEADDRESSSTATE_INUSEMANY
The monitored or bridged address has changed to being in use by one station to being used by more than one station.
LINEADDRESSSTATE_NUMCALLS
The number of calls on the address has changed, as a result of an event such as a new inbound call, an outbound call on the address, or a call changing its hold status.
LINEADDRESSSTATE_FORWARD
The forwarding status of the address has changed including the number of rings for determining a no-answer condition. TAPI checks the address status to determine details about the address's current forwarding status.
LINEADDRESSSTATE_TERMINALS
The terminal settings for the address have changed.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALADDRESSSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALLINESTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM.

Remarks

The service provider returns LINEERR_INVALLINESTATE if the dwLineStates parameter contains one or more bits that are not LINEDEVSTATE_ constants.

Win32 Telephony defines a number of messages that notify applications about events occurring on lines and addresses. The sets of all change messages in which all applications are interested can be much smaller than the set of possible messages. This procedure allows TAPI to tell the service provider the reduced set of messages to deliver. The service provider delivers all of the messages it supports, within the specified set. It is permitted to deliver more (they are filtered out by TAPI), but is discouraged from doing so for performance reasons. If TAPI requests delivery of a particular message type that is not produced by the provider, the provider nevertheless accepts the request but simply does not produce the message. By default, address and line status reporting is initially disabled for a line.

This function differs from the corresponding TAPI function as follows: (1) The set of messages requested is the union of all sets requested by applications at the TAPI level. (2) The message set is neither reduced nor augmented by ownership (because there is no concept of ownership at the TSPI level) (3) The set is advisory in the sense that the service provider is required to forward at least the indicated set of messages but is permitted to forward a larger set.

Device state changes regarding Open and Close are not reported, because at the TSPI level there is only one outstanding Open at a time.

See Also

LINE_ADDRESSSTATE, LINE_CLOSE, LINE_LINEDEVSTATE, LINEADDRESSSTATE_ Constants, LINEDEVSTATE_ Constants


TSPI_lineSetTerminal

The TSPI_lineSetTerminal function enables TAPI to specify to which terminal information related to the specified line, address, or call is to be routed. This operation can be used while calls are in progress on the line, to allow events to be routed to different devices as required.

LONG TSPI_lineSetTerminal(
  DRV_REQUESTID dwRequestID,
  HDRVLINE hdLine,
  DWORD dwAddressID,
  HDRVCALL hdCall,
  DWORD dwSelect,
  DWORD dwTerminalModes,
  DWORD dwTerminalID,
  DWORD bEnable
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdLine
The handle to a line.
dwAddressID
An address on the given open line device. TAPI does not validate this parameter when this function is called.
hdCall
The handle to a call. The call state can be any state (if dwSelect is LINECALLSELECT_CALL).
dwSelect
Specifies whether the terminal setting is requested for the line, the address, or just the specified call. If line or address is specified, events either apply to the line or address itself or serve as a default initial setting for all new calls on the line or address. This parameter uses the following LINECALLSELECT_ constants:
LINECALLSELECT_LINE
Select the specified line device. The hdLine parameter must be a valid line handle; hdCall and dwAddressID must be ignored.
LINECALLSELECT_ADDRESS
Select the specified address on the line. Both hdLine and dwAddressID must be valid; hdCall must be ignored. The service provider must validate dwAddressID; TAPI validates hdLine.
LINECALLSELECT_CALL
Select the specified call. The hdCall parameter must be valid; hdLine and dwAddressID must both be ignored.
dwTerminalModes
The class(es) of low level events to be routed to the given terminal.
LINETERMMODE_BUTTONS
The button presses from the terminal to the line.
LINETERMMODE_LAMPS
The lamp lighting events from the line to the terminal.
LINETERMMODE_DISPLAY
The display events from the line to the terminal.
LINETERMMODE_RINGER
The ring requests from the line to the terminal.
LINETERMMODE_HOOKSWITCH
The hookswitch events between the terminal and the line.
LINETERMMODE_MEDIATOLINE
The unidirectional media stream from the terminal to the line associated with a call on the line. This value is only allowed when routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIAFROMLINE
The unidirectional media stream from the line to the terminal associated with a call on the line. This value is only allowed when routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIABIDIRECT
The bidirectional media stream associated with a call on the line and the terminal. This is the only value allowed when routing of both unidirectional channels of a call's media stream cannot be controlled independently.

Note The media modes (1) MEDIABIDIRECT and (2) MEDIATOLINE and MEDIAFROMLINE are exclusive, the enforcement of which is the responsibility of the service provider.

dwTerminalID
The device identifier of the terminal device where the given events are to be routed. Terminal identifiers are small integers in the range from 0 through dwNumTerminals minus one, where dwNumTerminals and the terminal modes each terminal is capable of handling are indicated by the service provider in LINEDEVCAPS.

Note These terminal identifiers have no relation to other device identifiers and are defined by the service provider through device capabilities. TAPI does not validate this parameter when this function is called.

bEnable
If TRUE, dwTerminalID is valid and the specified event classes are routed to or from that terminal. If FALSE, these events are not routed to or from the dwTerminalID. TAPI does not validate this parameter when this function is called.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_INVALTERMINALID, LINEERR_INVALADDRESSID, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSELECT, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALTERMINALMODE, LINEERR_OPERATIONFAILED.

Remarks

The service provider returns LINEERR_RESOURCEUNAVAIL if the operation cannot be completed because of resource overcommitment or if too many terminals are set, due either to hardware limitations or to service provider/device driver limitations.

TAPI can use this operation to route certain classes of low-level line events to the specified terminal device, or to suppress the routing of these events altogether. For example, voice can be routed to a separate audio I/O device (headset), lamps and display events can be routed to the local phone device, and button events and ringer events can be suppressed altogether.

Call progress tones and/or messages get routed to the same place as media. For example, if audio signals are going to the phone, then so are busy signals (analog) or Q.931 messages indicating busy (digital).

The service provider must determine whether the combinations of dwSelect and dwTerminalModes are legal.

This operation can be called any time, even when a call is active on the given line device. This, for example, allows a user to switch from using the local phone set to another audio I/O device.

This function can be called multiple times to route the same events to multiple terminals simultaneously. To reroute events to a different terminal, TAPI recommends that the application first disable routing to the existing terminal and next route the events to the new terminal. However, the service provider should make its best effort to accomodate the application's requests in any sequence.

Terminal identifier assignments are made by the service provider, and LINEDEVCAPS indicates which terminal identifiers the service provider has available. Service providers that don't support this type of event routing indicate that they have no terminal devices (dwNumTerminals in LINEDEVCAPS is set to zero).

LineSetTerminal on a line or address affects all existing calls on that line or address, but does not affect calls on other addresses. It also sets the default for future calls on that line or address. A line or address that has multiple connected calls active at any one time can have different routing in effect for each call.

Disabling the routing of low-level events to a terminal when these events are not currently routed to or from that terminal is not required to generate an error so long as after the function succeeds, the specified events are not routed to or from that terminal.

See Also

ASYNC_COMPLETION, LINECALLSELECT_ Constants, LINETERMMODE_ Constants


TSPI_lineSetupConference

The TSPI_lineSetupConference function sets up a conference call for the addition of the third party.

LONG TSPI_lineSetupConference(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  HDRVLINE hdLine,
  HTAPICALL htConfCall,
  LPHDRVCALL lphdConfCall,
  HTAPICALL htConsultCall,
  LPHDRVCALL lphdConsultCall,
  DWORD dwNumParties,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the initial call that identifies the first party of a conference call. In some environments, a call must exist in order to start a conference call. In other telephony environments, no call initially exists and hdCall is left NULL. The call state of hdCall can be connected.
hdLine
The handle to the line device on which to originate the conference call if hdCall is NULL. The hdLine parameter is ignored if hdCall is non-NULL. The service provider reports which model it supports through the setupConfNull flag of the LINEADDRESSCAPS data structure.
htConfCall
The TAPI handle to the new conference call. The service provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the new call.
lphdConfCall
A pointer to an HDRVCALL representing the service provider's identifier for the newly created conference call. The service provider must fill this location with its handle for the new call before this procedure returns. This handle is ignored by TAPI if the function results in an error. The call state of hdConfCall is not applicable.
htConsultCall
The TAPI handle to the consultation call. When setting up a call for the addition of a new party, a new temporary call (consultation call) is automatically allocated. The service provider must save the htConsultCall and use it in all subsequent calls to the LINEEVENT procedure reporting events on the new consultation call.
lphdConsultCall
A pointer to an HDRVCALL representing the service provider's identifier for a call. When setting up a call for the addition of a new party, a new temporary call (consultation call) is automatically allocated. The service provider must fill this location with its handle for the new consultation call before this procedure returns. This handle is ignored by TAPI if the function results in an error. The call state of hdConsultCall is not applicable.
dwNumParties
The expected number of parties in the conference call. The service provider is free to do with this number as it pleases. For example, the service provider can ignore it, or use it as a hint to allocate the right size conference bridge inside the switch. TAPI does not validate this parameter when this function is called.
lpCallParams
A pointer to call parameters to be used when establishing the consultation call. This parameter is set to NULL if no special call setup parameters are desired and the service provider uses default parameters.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_INVALADDRESSMODE, LINEERR_INVALLINEHANDLE, LINEERR_INVALBEARERMODE, LINEERR_INVALCALLSTATE, LINEERR_INVALCALLPARAMS, LINEERR_CALLUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_CONFERENCEFULL, LINEERR_INVALMEDIAMODE, LINEERR_NOMEM, LINEERR_INVALRATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INUSE, LINEERR_OPERATIONFAILED, LINEERR_RATEUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_USERUSERINFOTOOBIG, LINEERR_BEARERMODEUNAVAIL.

Remarks

The service provider returns LINEERR_INVALLINEHANDLE if the specified line handle for the line containing the conference call is invalid. This error can also indicate that the telephony environment requires an initial line to set up a conference but a non-NULL call handle was supplied instead.

The service provider returns LINEERR_INVALCALLHANDLE if the telephony environment requires an initial call to set up a conference but a NULL call handle was supplied instead.

TSPI_lineSetupConference provides two ways to establish a new conference call, depending on whether a normal two-party call is required to pre-exist or not. When setting up a conference call from an existing two-party call, the hdCall parameter is a valid call handle that is initially added to the conference call by the TSPI_lineSetupConference request and hdLine is ignored. On switches where conference call setup does not start with an existing call, hdCall must be NULL and hdLine must be specified to identify the line device on which to initiate the conference call. In either case, a consultation call is allocated for connecting to the party that is to be added to the call. TAPI can use TSPI_lineDial to dial the address of the other party.

The conference call typically transitions into the onHoldPendingConference state, the consultation call dialtone state and the initial call (if one) into the conferenced state.

A conference call can also be set up using a TSPI_lineCompleteTransfer function that is resolved into a three-way conference.

TAPI may be able to toggle between the consultation call and the conference call using TSPI_lineSwapHold.

The TSPI_lineUnhold function can recover calls that have the call state onHoldPendingConference. If this is done, any consultation call typically goes to the idle state.

A consultation call can be canceled by invoking TSPI_lineDrop on it. When dropping a consultation call, the existing conference call typically transitions back to the connected state. TAPI and its client applications should observe the LINE_CALLSTATE messages to determine exactly what happens to the calls. For example, if the conference call reverts back to a regular two-party call, the conference call becomes idle and the original participant call may revert to connected.

This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETION message reports success. In other words, it must not issue any LINEEVENT messages for the new call or include it in call counts in messages or status data structures for the line.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, LINEADDRESSCAPS, LINEADDRCAPFLAGS_ Constants, LINEEVENT, TSPI_lineAddToConference, TSPI_lineDial, TSPI_linePrepareAddToConference, TSPI_lineRemoveFromConference, TSPI_lineSwapHold


TSPI_lineSetupTransfer

The TSPI_lineSetupTransfer function initiates a transfer of the call specified by hdCall. It establishes a consultation call, lphdConsultCall, on which the party can be dialed that can become the destination of the transfer.

LONG TSPI_lineSetupTransfer(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall,
  HTAPICALL htConsultCall,
  LPHDRVCALL lphdConsultCall,
  LPLINECALLPARAMS const lpCallParams
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the call to be transferred. The call state of hdCall can be connected.
htConsultCall
The TAPI handle to the new, temporary consultation call. The service provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the new consultation call.
lphdConsultCall
A pointer to an HDRVCALL representing the service provider's identifier for the new consultation call. The service provider must fill this location with its handle for the new consultation call before this procedure returns. This handle is ignored by TAPI if the function results in an error. The call state of hdConsultCall is not applicable.

When setting a call up for transfer, another call (a consultation call) is automatically allocated to enable the application (through TAPI) to dial the address (using TSPI_lineDial) of the party to where the call is to be transferred. The originating party can carry on a conversation over this consultation call prior to completing the transfer.

This transfer procedure may not be valid for some line devices. Instead of calling this procedure, TAPI may need to unhold an existing held call (using TSPI_lineUnhold) to identify the destination of the transfer. On switches that support cross-address call transfer, the consultation call can exist on a different address than the call to be transferred. It may also be necessary to set up the consultation call as an entirely new call using TSPI_lineMakeCall, to the destination of the transfer.

The transferHeld and transferMake flags in the LINEADDRESSCAPS data structure report what model the service provider uses.

lpCallParams
A pointer to call parameters to be used when establishing the consultation call. This parameter can be set to NULL if no special call setup parameters are desired (the service provider uses defaults).

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_INVALBEARERMODE, LINEERR_INVALCALLSTATE, LINEERR_INVALRATE, LINEERR_CALLUNAVAIL, LINEERR_INVALCALLPARAMS, LINEERR_NOMEM, LINEERR_INVALLINESTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_OPERATIONFAILED, LINEERR_INUSE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_BEARERMODEUNAVAIL, LINEERR_RATEUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_USERUSERINFOTOOBIG.

Remarks

The service provider returns LINEERR_INVALCALLSTATE if the call to be transferred is not in a valid state.

This operation sets up the transfer of the call specified by hdCall. The setup phase of a transfer establishes a consultation call to send the address of the destination (the party to be transferred to) to the switch, while the call to be transferred is kept on hold. This new call is referred to as a consultation call (hdConsultCall) and can be manipulated (for example, dropped) independently of the original call.

When the consultation call has reached the dialtone call state, TAPI can continue transferring the call either by dialing the destination address and tracking its progress, or by unholding an existing call. The transfer of the original call to the selected destination is completed using TSPI_lineCompleteTransfer.

While the consultation call exists, the original call typically transitions to the onholdPendingTransfer state.

The TSPI_lineUnhold function can recover calls that have the call state onHoldPendingTransfer. If this is done, any consultation call typically goes to the idle state.

In telephony environments that follow the transferHeld or transferMake transfer models, this procedure returns LINEERR_OPERATIONFAILED and does not allocate a consultation call handle.

A consultation call can be canceled by invoking TSPI_lineDrop on it. After dropping a consultation call, the original call typically transitions back to the connected state.

This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETION message reports success. In other words, it must not issue any LINEEVENT messages for the new call or include it in call counts in messages or status data structures for the line.

See Also

LINE_CALLSTATE, LINEADDRESSCAPS, TSPI_lineBlindTransfer, TSPI_lineCompleteTransfer, TSPI_lineDial, TSPI_lineDrop, TSPI_lineSwapHold, TSPI_lineUnhold


TSPI_lineSwapHold

The TSPI_lineSwapHold function swaps the specified active call with the specified call on consultation hold.

LONG TSPI_lineSwapHold(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdActiveCall,
  HDRVCALL hdHeldCall
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdActiveCall
The handle to the call to be swapped with the call on consultation hold. The call state of hdActiveCall can be connected.
hdHeldCall
The handle to the consultation call. The call state of hdHeldCall can be onHoldPendingTransfer, onHoldPendingConference, or onHold.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

The service provider must send LINE_CALLSTATE messages for the call transitions.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, TSPI_lineSetupConference, TSPI_lineSetupTransfer


TSPI_lineUncompleteCall

The TSPI_lineUncompleteCall function is used to cancel the specified call competion request on the specified line.

LONG TSPI_lineUncompleteCall(
  DRV_REQUESTID dwRequestID,
  HDRVLINE hdLine,
  DWORD dwCompletionID
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdLine
The handle to the line on which a call completion is to be canceled.
dwCompletionID
The completion identifier for the request that is to be canceled. TAPI does not validate this parameter when this function is called.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCOMPLETIONID, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

See Also

ASYNC_COMPLETION, TSPI_lineCompleteCall


TSPI_lineUnhold

The TSPI_lineUnhold function retrieves the specified held call.

LONG TSPI_lineUnhold(
  DRV_REQUESTID dwRequestID,
  HDRVCALL hdCall
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdCall
The handle to the call to be retrieved. The call state of hdCall can be onHold.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

The service provider returns LINEERR_INVALCALLSTATE if the call is not currently on hold.

This operation works for calls on hard hold (calls placed on hold using TSPI_lineHold) and on soft hold. The service provider should check that the call is currently in the onHold, onHoldPendingTransfer, or onHoldPendingConference state, change the state to connected, and send a LINECALLSTATE message for the new call state.

See Also

ASYNC_COMPLETION, LINE_CALLSTATE, TSPI_lineHold


TSPI_lineUnpark

The TSPI_lineUnpark function retrieves the call parked at the specified address and returns a call handle for it.

LONG TSPI_lineUnpark(
  DRV_REQUESTID dwRequestID,
  HDRVLINE hdLine,
  DWORD dwAddressID,
  HTAPICALL htCall,
  LPHDRVCALL lphdCall,
  LPCWSTR lpszDestAddress
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdLine
The handle to the line on which a call is to be unparked.
dwAddressID
The address on hdLine at which to originate the unpark. TAPI does not validate this parameter when this function is called.
htCall
The TAPI handle to the new unparked call. The service provider must save this and use it in all subsequent calls to the LINEEVENT procedure reporting events on the call.
lphdCall
A pointer to an HDRVCALL representing the service provider's identifier for the new unparked call. The service provider must fill this location with its handle for the call before this procedure returns. This handle is invalid if the function results in an error.
lpszDestAddress
A pointer to a NULL-terminated Unicode string that contains the address where the call is parked. The address is in dialable address format.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESS, LINEERR_RESOURCEUNAVAIL.

Remarks

This function differs from the corresponding TAPI function in that it follows the TSPI model for beginning the lifetime of a call. TAPI and the service provider exchange opaque handles representing the call with one another. In addition, the service provider is permitted to do callbacks for the new call before it returns from this procedure. In any case, the service provider must also treat the handle it returned as "not yet valid" until after the matching ASYNC_COMPLETION message reports success. In other words, it must not issue any LINEEVENT messages for the new call or include it in call counts in messages or status data structures for the line.

The call handle created by this function is a new, distinct, call handle even if an original call handle for the call is still in existence (it has not been destroyed by TSPI_lineCloseCall).

See Also

ASYNC_COMPLETION, TSPI_lineCloseCall, TSPI_linePark


TSPI Phone Device Functions

This section contains an alphabetic list of the phone device functions in the Telephony SPI.


TSPI_phoneClose

The TSPI_phoneClose function closes the specified open phone device after completing or aborting all outstanding asynchronous operations on the device.

long TSPI_phoneClose(
  HDRVPHONE hdPhone
);

Parameters

hdPhone
The service provider's opaque handle to the phone to be closed. After the phone is successfully closed, this handle is no longer valid.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_RESOURCEUNAVAIL.

Remarks

The service provider must report completion for every asynchronous operation. If this procedure is called for a phone on which there are outstanding asynchronous operations, the operations should be reported complete with an appropriate result or error code before this procedure returns. Generally, TAPI waits for these to complete in an orderly fashion. However, the service provider should be prepared to handle an early call to TSPI_phoneClose in "abort" or "emergency shutdown" situtations.

After this procedure returns the service provider must report no further events on the phone. The service provider's opaque handle for the phone becomes invalid.

The service provider must relinquish nonsharable resources it reserves while the phone is open. For example, closing a phone accessed through a comm port and modem should result in closing the comm port, making it available for use by other applications.

This function should always succeed except in extraordinary circumstances. Most callers will probably ignore the return code because they will be unable to compensate for any error that occurs. The specified return values are more advisory for development diagnostic purposes than anything else.

See Also

PHONE_CLOSE


TSPI_phoneConfigDialog

The TSPI_phoneConfigDialog function is obsolete.TAPI version 1.4 or earlier service providers can implement this TSPI function. TAPI version 2.0 or later TSPs implement TUISPI_phoneConfigDialog.

The TSPI_phoneConfigDialog function causes the provider of the specified phone device to display a modal dialog box as a child window of hwndOwner to allow the user to configure parameters related to the phone device.

LONG TSPI_phoneConfigDialog(
  DWORD dwDeviceID,
  HWND hwndOwner,
  LPCWSTR lpszDeviceClass
);

Parameters

dwDeviceID
The phone device to be configured.
hwndOwner
A handle to a parent window in which the dialog box window is to be placed.
lpszDeviceClass
A pointer to a NULL-terminated string that identifies a device class name. This device class allows the caller to select a specific subscreen of configuration information applicable to that device class. If this parameter is NULL or an empty string, the highest level configuration dialog box is selected.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_BADDEVICEID, PHONEERR_NOMEM, PHONEERR_INUSE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPARAM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALDEVICECLASS, PHONEERR_RESOURCEUNAVAIL.

Remarks

TSPI_phoneConfigDialog causes the service provider to display a modal dialog box as a child window of hWndOwner to allow the user to configure parameters related to the phone specified by dwDeviceID. The lpszDeviceClass parameter allows the application to select a specific subscreen of configuration information applicable to the device class in which the user is interested. The permitted strings are the same as for TSPI_phoneGetID. For example, if the phone supports the Comm API, passing comm/datamodem as lpszDeviceClass causes the provider to display the parameters related specifically to Comm (or, at least, to start at the corresponding point in a multilevel configuration dialog box chain, so that the user doesn't have to search to find the desired parameters). The szDeviceClass parameter should be "tapi/phone", "", or NULL to cause the provider to display the highest level configuration for the phone.

The procedure must update the [Windows Telephony] section in the win.ini file and broadcast the WM_WININICHANGE message if it makes any changes to telephon.ini that affect the contents of structures visible to applications (such as PHONECAPS), or if phone devices are created or removed.

See Also

PHONECAPS, TSPI_phoneGetID


TSPI_phoneDevSpecific

The TSPI_phoneDevSpecific function is used as a general extension mechanism to enable a Telephony API implementation to provide features not described in the other operations. The meanings of these extensions are device specific.

LONG TSPI_phoneDevSpecific(
  DRV_REQUESTID dwRequestID,
  HDRVPHONE hdPhone,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdPhone
The handle to the phone on which a device-specific operation is to be performed.
lpParams
A pointer to a memory area used to hold a parameter block. Its interpretation is device specific. The lpParams parameter should not contain pointers. To get information back to the application from TSPI_phoneDevSpecific, the service provider sends a PHONE_DEVSPECIFIC message with the information.
dwSize
The size in bytes of the parameter block area.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or it is an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_NOMEM, PHONEERR_OPERATIONFAILED, PHONEERR_RESOURCEUNAVAIL.

Remarks

Additional return values are device specific.

This operation provides a generic parameter profile. The interpretation of the parameter block is device specific. Indications and replies that are device specific should use the PHONE_DEVSPECIFIC message.

This function is called in direct response to an application that has called the TAPI phoneDevSpecific function. TAPI translates the hPhone parameter used at the TAPI level to the corresponding hdPhone parameter used at the TSPI level. The lpParams buffer is passed through unmodified.

A service provider can provide access to device-specific functions by defining parameters for use with this operation. Applications that want to make use of these device-specific extensions should consult the device-specific (vendor-specific) documentation that describes what extentions are defined.

Note An application that relies on these device-specific extensions is typically not portable in working with other service provider environments.

See Also

ASYNC_COMPLETION, PHONE_DEVSPECIFIC


TSPI_phoneGetButtonInfo

The TSPI_phoneGetButtonInfo function returns information about a specified button.

LONG TSPI_phoneGetButtonInfo(
  HDRVPHONE hdPhone,
  DWORD dwButtonLampID,
  LPPHONEBUTTONINFO lpButtonInfo
);

Parameters

hdPhone
The handle to the phone to be queried.
dwButtonLampID
A button on the phone device.
lpButtonInfo
A pointer to memory into which the service provider writes a variably sized structure of type PHONEBUTTONINFO. This data structure describes the mode and function, and provides additional descriptive text corresponding to the button. Prior to calling TSPI_phoneGetButtonInfo, the application sets the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALBUTTONLAMPID, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NOMEM.

Remarks

The TSPI_phoneGetButtonInfo function returns the PHONEERR_NOMEM value if the service provider cannot access the memory containing the button information.

The service provider fills in all the members of the PHONEBUTTONINFO data structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSize member.

See Also

PHONEBUTTONINFO, PHONECAPS, TSPI_phoneSetButtonInfo


TSPI_phoneGetData

The TSPI_phoneGetData function uploads the information from the specified location in the open phone device to the specified buffer.

LONG TSPI_phoneGetData(
  HDRVPHONE hdPhone,
  DWORD dwDataID,
  LPVOID lpData,
  DWORD dwSize
);

Parameters

hdPhone
The handle to the phone to be queried.
dwDataID
Specifies where in the phone device the buffer is to be uploaded from.
lpData
A pointer to the memory buffer where the data is to be uploaded to.
dwSize
The size of the data buffer in bytes.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALDATAID, PHONEERR_RESOURCEUNAVAIL.

Remarks

The TSPI_phoneGetData function uploads a maximum of dwSize bytes from the phone device into lpData. If dwSize is zero, nothing is copied. The size of each data area is listed in the phone's PHONECAPS structure.

See Also

PHONECAPS, TSPI_phoneGetDevCaps, TSPI_phoneSetData


TSPI_phoneGetDevCaps

The TSPI_phoneGetDevCaps function queries a specified phone device to determine its telephony capabilities.

LONG TSPI_phoneGetDevCaps(
  DWORD dwDeviceID,
  DWORD dwTSPIVersion,
  DWORD dwExtVersion,
  LPPHONECAPS lpPhoneCaps
);

Parameters

dwDeviceID
The phone device to be queried.
dwTSPIVersion
The negotiated TSPI version number. This value is negotiated for this device through the TSPI_phoneNegotiateTSPIVersion function.
dwExtVersion
The negotiated extension version number. This value is negotiated for this device through the TSPI_phoneNegotiateExtVersion function.
lpPhoneCaps
A pointer to memory into which the service provider writes a variably sized structure of type PHONECAPS. Upon successful completion of the request, this structure is filled with phone device capability information. Prior to calling TSPI_phoneGetDevCaps, the application sets the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_OPERATIONFAILED, PHONEERR_NODRIVER, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

Remarks

The service provider fills in all the members of the PHONEBUTTONINFO data structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSize member.

If dwExtVersion is zero, no extension information is requested. If it is nonzero, it holds a value that has already been negotiated for this device with the TSPI_phoneNegotiateExtVersion function. The service provider fills in device- and vendor-specific extended information according to the extension version specified.

After the service provider returns from the TSPI_phoneGetDevCaps function, TAPI sets the dwPhoneStates member of the PHONECAPS structure as follows:

PHONECAPS.dwPhoneStates |=
    PHONESTATE_OWNER |
    PHONESTATE_MONITORS |
    PHONESTATE_REINIT;

See Also

PHONEBUTTONINFO, PHONECAPS, TSPI_phoneNegotiateExtVersion


TSPI_phoneGetDisplay

The TSPI_phoneGetDisplay function returns the current contents of the specified phone display.

LONG TSPI_phoneGetDisplay(
  HDRVPHONE hdPhone,
  LPVARSTRING lpDisplay
);

Parameters

hdPhone
The handle to the phone to be queried.
lpDisplay
A pointer to the memory location where the display content is to be stored by the provider, of type VARSTRING. Prior to calling TSPI_phoneGetDisplay, the application sets the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL.

Remarks

The lpDisplay memory area should be at least dwDisplayNumRows * dwDisplayNumColumns elements in size to receive all of the display information. The dwDisplayNumRows and dwDisplayNumColumns members are available in the PHONECAPS structure returned by TSPI_phoneGetDevCaps.

The service provider fills in all the members of the VARSTRING data structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSize member.

See Also

PHONECAPS, TSPI_phoneGetDevCaps, TSPI_phoneSetDisplay, VARSTRING


TSPI_phoneGetExtensionID

The TSPI_phoneGetExtensionID function retrieves the extension identifier that the service provider supports for the indicated phone device.

LONG TSPI_phoneGetExtensionID(
  DWORD dwDeviceID,
  DWORD dwTSPIVersion,
  LPPHONEEXTENSIONID lpExtensionID
);

Parameters

dwDeviceID
The phone device to be queried.
dwTSPIVersion
Specifies an interface version number that is negotiated for this device using TSPI_phoneNegotiateTSPIVersion. This function operates according to the interface specification at this version level.
lpExtensionID
A pointer to a structure of type PHONEEXTENSIONID. If the service provider supports provider-specific extensions, it fills this structure with the extension identifier of these extensions. If the service provider does not support extensions, it fills this structure with all zeros. An extension identifier of all zeros is not a legal extension identifier, since the all-zeros value is used to indicate that the service provider does not support extensions.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NODRIVER, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL.

Remarks

This function is typically called by TAPI in response to an application calling the phoneNegotiateAPIVersion function. The result returned by the service provider should be appropriate for use in a subsequent call to TSPI_phoneNegotiateExtVersion.

See Also

PHONEEXTENSIONID, TSPI_phoneNegotiateExtVersion, TSPI_phoneNegotiateTSPIVersion


TSPI_phoneGetGain

The TSPI_phoneGetGain function returns the gain setting of the microphone of the specified phone's hookswitch device.

LONG TSPI_phoneGetGain(
  HDRVPHONE hdPhone,
  DWORD dwHookSwitchDev,
  LPDWORD lpdwGain
);

Parameters

hdPhone
The handle to the phone whose gain is to be retrieved.
dwHookSwitchDev
The hookswitch device whose gain level is queried. This parameter can only have a single bit set. Values are:
PHONEHOOKSWITCHDEV_HANDSET
The phone's handset.
PHONEHOOKSWITCHDEV_SPEAKER
The phone's speakerphone or adjunct.
PHONEHOOKSWITCHDEV_HEADSET
The phone's headset.
lpdwGain
A pointer to a DWORD-sized location into which the service provider writes the current gain setting of the hookswitch microphone component. The dwGain gain parameter specifies the volume level of the hookswitch device. This is a number in the range from 0x00000000 (silence) through 0x0000FFFF (maximum volume). The actual granularity and quantization of gain settings in this range are service provider-specific.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

See Also

PHONECAPS, TSPI_phoneGetDevCaps, TSPI_phoneSetGain


TSPI_phoneGetHookSwitch

The TSPI_phoneGetHookSwitch function returns the current hookswitch mode of the specified open phone device.

LONG TSPI_phoneGetHookSwitch(
  HDRVPHONE hdPhone,
  LPDWORD lpdwHookSwitchDevs
);

Parameters

hdPhone
The service provider's opaque handle to the phone whose hookswitch mode is to be retrieved.
lpdwHookSwitchDevs
A pointer to a DWORD-sized location into which the service provider writes the mode of the phone's hookswitch devices. This parameter uses the PHONEHOOKSWITCHDEV_ constants listed below. If a bit position is FALSE, the corresponding hookswitch device is onhook. If TRUE, the microphone and/or speaker part of the corresponding hookswitch device is offhook. To find out whether microphone and/or speaker are enabled, TAPI can use TSPI_phoneGetStatus. Values for lpdwHookSwitchDevs are:
PHONEHOOKSWITCHDEV_HANDSET
The phone's handset.
PHONEHOOKSWITCHDEV_SPEAKER
The phone's speakerphone or adjunct.
PHONEHOOKSWITCHDEV_HEADSET
The phone's headset.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL.

Remarks

After the hookswitch state of a device changes, and if hookswitch monitoring is enabled, TAPI is sent a PHONE_STATE message.

See Also

PHONE_STATE, PHONEHOOKSWITCHDEV_ Constants, PHONESTATUS, TSPI_phoneGetStatus, TSPI_phoneSetHookSwitch


TSPI_phoneGetIcon

The TSPI_phoneGetIcon function retrieves a service phone device-specific (or provider-specific) icon to display to the user.

LONG TSPI_phoneGetIcon(
  DWORD dwDeviceID,
  LPCWSTR lpszDeviceClass,
  LPHICON lphIcon
);

Parameters

dwDeviceID
The phone device whose icon is requested.
lpszDeviceClass
A pointer to a NULL-terminated Unicode string that identifies a device class name. This device class allows the caller to select a specific sub icon applicable to that device class. This parameter is optional and can be left NULL or be empty, in which case the highest level icon associated with the phone device rather than a specified media stream device is selected.
lphIcon
A pointer to a memory location in which the handle to the icon is returned.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALDEVICECLASS, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_RESOURCEUNAVAIL.

Remarks

TSPI_phoneGetIcon causes the provider to return a handle (in the DWORD pointed to by lphIcon) to an icon resource (obtained from the Win32 LoadIcon function) associated with the specified phone. The icon handle is for a resource associated with the provider.

The lpszDeviceClass parameter allows the provider to return different icons based on the type of service being referenced by the caller. The permitted strings are the same as for TSPI_phoneGetID. For example, if the phone supports the Comm API, passing comm/datamodem as lpszDeviceClass causes the provider to return an icon related specifically to the Comm device functions of the service provider. For more information about common device classes, see TSPI Device Classes.

The parameters "tapi/phone", "", or NULL can be used to request the icon for the phone device. A provider can choose to support many icons (selected by lpszDeviceClass and/or phone number), a single icon (such as for the manufacturer, which would be returned for all phoneGetIcon requests regardless of the lpszDeviceClass selected), or no icons, in which case it sets the DWORD pointed to by lphIcon to NULL. TAPI examines the handle returned by the provider, and if the provider returns NULL, TAPI substitutes a generic Win32 Telephony icon included as a resource in TAPI (the generic phone icon).

If the service provider supports no icons, it can leave this function unimplemented, in which case TAPI provides a generic phone icon for the application.

See Also

TSPI_phoneConfigDialog, TSPI_phoneGetID


TSPI_phoneGetID

The TSPI_phoneGetID function returns a device identifier for the given device class associated with the specified phone device.

LONG TSPI_phoneGetID(
  HDRVPHONE hdPhone,
  LPVARSTRING lpDeviceID,
  LPCWSTR lpszDeviceClass,
  HANDLE hTargetProcess
);

Parameters

hdPhone
The handle to the phone to be queried.
lpDeviceID
A pointer to a data structure of type VARSTRING where the device identifier is returned. The format of the returned information depends on the method used by the device class (API) for naming devices. Prior to calling TSPI_phoneGetID, the application sets the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.
lpszDeviceClass
A pointer to a NULL-terminated Unicode string that specifies the device class of the device whose identifier is requested.
hTargetProcess
The process handle of the application on behalf of which the TSPI_phoneGetID function is being invoked. If the information being returned in the VARSTRING structure includes a handle for use by the application, the service provider creates or duplicates the handle for the process.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALDEVICECLASS, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL.

Remarks

This operation can be used to retrieve a phone device identifier given a phone handle. It can also be used to obtain the device identifier of the media device (for device classes such as COM, wave, MIDI, phone, line, and mciwave) associated with the opened phone device. This identifier can then be used with the appropriate media API (such as mci, midi, and wav) to select the corresponding device. For more information about common device class names, see TSPI Device Classes.

The service provider fills in all the members of the VARSTRING data structure, except for dwTotalSize, which is filled in by TAPI. The service provider must not overwrite the dwTotalSize member.

The service provider does not need to be concerned with handling tapi/line and tapi/phone device classes because TAPI handles these for the service provider. Therefore, code for handling these device classes is optional.

See Also

VARSTRING


TSPI_phoneGetLamp

The TSPI_phoneGetLamp function returns the current lamp mode of the specified lamp.

LONG TSPI_phoneGetLamp(
  HDRVPHONE hdPhone,
  DWORD dwButtonLampID,
  LPDWORD lpdwLampMode
);

Parameters

hdPhone
The handle to the phone whose lamp mode is to be retrieved.
dwButtonLampID
The identifier of the lamp to be queried.
lpdwLampMode
A pointer to a memory location into which the service provider writes the lamp mode status of the given lamp. This parameter can have at most one of the following PHONELAMPMODE_ bits set:
PHONELAMPMODE_BROKENFLUTTER
Broken flutter is the superposition of flash and flutter.
PHONELAMPMODE_FLASH
Flash means slow on and off.
PHONELAMPMODE_FLUTTER
Flutter means fast on and off.
PHONELAMPMODE_OFF
The lamp is off.
PHONELAMPMODE_STEADY
The lamp is continuously lit.
PHONELAMPMODE_WINK
The lamp is winking.
PHONELAMPMODE_UNKNOWN
The lamp mode is currently unknown.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALBUTTONLAMPID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

Remarks

Phone sets that have multiple lamps per button should be modeled using multiple button/lamps pairs. Each additional button/lamp pair should use a DUMMY button.

See Also

PHONECAPS, PHONELAMPMODE_ Constants, TSPI_phoneGetDevCaps, TSPI_phoneSetLamp


TSPI_phoneGetRing

The TSPI_phoneGetRing function enables an application to query the specified open phone device as to its current ring mode.

LONG TSPI_phoneGetRing(
  HDRVPHONE hdPhone,
  LPDWORD lpdwRingMode,
  LPDWORD lpdwVolume
);

Parameters

hdPhone
The handle to the phone whose ring mode is to be queried.
lpdwRingMode
The ringing pattern with which the phone is ringing. Zero indicates that the phone is not ringing.
lpdwVolume
The volume level with which the phone is ringing. This is a number in the range from 0x00000000 (silence) through 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service-provider specific.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL.

Remarks

The service provider defines the actual audible ringing patterns corresponding to each of phone's ring modes.

See Also

PHONECAPS, TSPI_phoneGetDevCaps, TSPI_phoneSetRing


TSPI_phoneGetStatus

The TSPI_phoneGetStatus function queries the specified open phone device for its overall status.

LONG TSPI_phoneGetStatus(
  HDRVPHONE hdPhone,
  LPPHONESTATUS lpPhoneStatus
);

Parameters

hdPhone
The handle to the phone to be queried.
lpPhoneStatus
A pointer to a variably sized data structure of type PHONESTATUS, into which the service provider writes information about the phone's status. Prior to calling TSPI_phoneGetStatus, the application sets the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_RESOURCEUNAVAIL.

Remarks

The following table indicates which members of the PHONESTATUS data structure are filled in by TAPI and which members are filled in by the service provider. The service provider must not overwrite the values filled in by TAPI.

Member | TAPI | Service Provider
dwTotalSize; | X |
dwNeededSize; |  | X
dwUsedSize; |  | X
dwStatusFlags; |  | X
dwNumOwners; | X |
dwNumMonitors; | X |
dwRingMode; |  | X
dwRingVolume; |  | X
dwHandsetHookSwitchMode; |  | X
dwHandsetVolume; |  | X
dwHandsetGain; |  | X
dwSpeakerHookSwitchMode; |  | X
dwSpeakerVolume; |  | X
dwSpeakerGain; |  | X
dwHeadsetHookSwitchMode; |  | X
dwHeadsetVolume; |  | X
dwHeadsetGain; |  | X
dwDisplaySize; |  | X
dwDisplayOffset; |  | X
dwLampModesSize; |  | X
dwLampModesOffset; |  | X
dwOwnerNameSize; | X |
dwOwnerNameOffset; | X |
dwDevSpecificSize; |  | X
dwDevSpecificOffset; |  | X

TAPI can use this function to determine the current state of an open phone device. The status information describes information about the phone device's hookswitch devices, ringer, volume, display, and lamps of the open phone.

See Also

PHONE_STATE, PHONESTATUS


TSPI_phoneGetVolume

The TSPI_phoneGetVolume function returns the volume setting of the specified phone's hookswitch device.

LONG TSPI_phoneGetVolume(
  HDRVPHONE hdPhone,
  DWORD dwHookSwitchDev,
  LPDWORD lpdwVolume
);

Parameters

hdPhone
The handle to the phone containing the hookswitch device whose volume setting is to be retrieved.
dwHookSwitchDev
Identifies a single hookswitch device whose volume level is queried. This parameter uses the following PHONEHOOKSWITCHDEV_ constants:
PHONEHOOKSWITCHDEV_HANDSET
The phone's handset.
PHONEHOOKSWITCHDEV_SPEAKER
The phone's speakerphone or adjunct.
PHONEHOOKSWITCHDEV_HEADSET
The phone's headset.
lpdwVolume
A pointer to a DWORD-sized location into which the service provider writes the current volume setting of the hookswitch device. This is a number in the range from 0x00000000 (silence) through 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service-provider specific.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, HONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

See Also

PHONECAPS, TSPI_phoneGetDevCaps, TSPI_phoneSetVolume


TSPI_phoneNegotiateExtVersion

The TSPI_phoneNegotiateExtVersion function returns the highest extension version number the service provider can operate under for this device, given the range of possible extension versions.

LONG TSPI_phoneNegotiateExtVersion(
  DWORD dwDeviceID,
  DWORD dwTSPIVersion,
  DWORD dwLowVersion,
  DWORD dwHighVersion,
  LPDWORD lpdwExtVersion
);

Parameters

dwDeviceID
Identifies the phone device for which interface version negotiation is to be performed.
dwTSPIVersion
Specifies an interface version number that is negotiated for this device using TSPI_phoneNegotiateTSPIVersion. This function operates according to the interface specification at this version level.
dwLowVersion
The lowest extension version number under which TAPI or its client application can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number.
dwHighVersion
The highest extension version number under which TAPI or its client application can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number.
lpdwExtVersion
A pointer to a DWORD. Upon a successful return from this function, the service provider fills this location with the highest extension version number, within the range requested by the caller, under which the service provider can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number. If the requested range does not overlap the range supported by the service provider, the function returns PHONEERR_INCOMPATIBLEEXTVERSION.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_OPERATIONFAILED, PHONEERR_NODRIVER, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

Remarks

This function can be called before or after the device has been opened by TAPI. If the device is currently open and has an extension version selected, the function should return that version number if it is within the requested range. If the selected version number is outside the requested range, the function returns PHONEERR_INCOMPATIBLEEXTVERSION.

See Also

TSPI_phoneNegotiateTSPIVersion


TSPI_phoneNegotiateTSPIVersion

The TSPI_phoneNegotiateTSPIVersion function returns the highest SPI version the service provider can operate under for this device, given the range of possible SPI versions.

LONG TSPI_phoneNegotiateTSPIVersion(
  DWORD dwDeviceID,
  DWORD dwLowVersion,
  DWORD dwHighVersion,
  LPDWORD lpdwTSPIVersion
);

Parameters

dwDeviceID
The phone device for which interface version negotiation is to be performed. Permitted values are strictly within the range of phone devices identifiers for this service provider; the value INITIALIZE_NEGOTIATION is never passed to this function.
dwLowVersion
The lowest TSPI version number under which TAPI can operate. The most significant WORD is the major version number and the least significant WORD is the minor version number.
dwHighVersion
The highest TSPI version number under which TAPI can operate. The most significant WORD is the major version number and the least significant WORD is the minor version number.
lpdwTSPIVersion
A pointer to a DWORD. Upon a successful return from this function the service provider fills this location with the highest TSPI version number, within the range requested by the caller, under which the service provider can operate. The most-significant WORD is the major version number and the least-significant WORD is the minor version number. If the requested range does not overlap the range supported by the service provider, the function returns PHONEERR_INCOMPATIBLEAPIVERSION.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NODRIVER, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL.

Remarks

The service provider returns PHONEERR_OPERATIONUNAVAIL if the operation is not available. However, if the service provider supports any phone devices, it must also support this function and the function must not return PHONEERR_OPERATIONUNAVAIL.

TAPI calls this function early in the initialization sequence for each phone device.

Negotiation of an extension version is done through the separate procedure TSPI_phoneNegotiateExtVersion.

The corresponding function at the TAPI level is an overloaded function that also retrieves the extension identifier, if any, supported by the service provider. At the TSPI level, retrieving the extension identifier is accomplished through a separate procedure, namely, TSPI_phoneGetExtensionID.

See Also

INITIALIZE_NEGOTIATION, TSPI_phoneGetExtensionID, TSPI_phoneNegotiateExtVersion


TSPI_phoneOpen

The TSPI_phoneOpen function opens the phone device whose device identifier is given, returning the service provider's opaque handle for the device and retaining TAPI's opaque handle for the device for use in subsequent calls to the PHONEEVENT procedure.

LONG TSPI_phoneOpen(
  DWORD dwDeviceID,
  HTAPIPHONE htPhone,
  LPHDRVPHONE lphdPhone,
  DWORD dwTSPIVersion,
  PHONEEVENT lpfnEventProc
);

Parameters

dwDeviceID
The phone device to be opened.
htPhone
The TAPI opaque handle for the phone device to be used in subsequent calls to the PHONEEVENT callback procedure to identify the device.
lphdPhone
A pointer to an HDRVPHONE where the service provider writes its handle for the phone device to be used by TAPI in subsequent calls to identify the device.
dwTSPIVersion
The TSPI version negotiated through TSPI_phoneNegotiateTSPIVersion under which the service provider can operate.
lpfnEventProc
A pointer to the PHONEEVENT callback procedure supplied by TAPI that the service provider calls to report subsequent events on the phone.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_ALLOCATED, PHONEERR_NOMEM, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NODRIVER, PHONEERR_OPERATIONFAILED, PHONEERR_INUSE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INIFILECORRUPT.

Remarks

Opening a phone entitles TAPI to make further requests on the phone. The phone becomes active in the sense that the service provider can report asynchronous events such as hookswitch changes or button presses. The service provider reserves whatever nonsharable resources are required to manage the phone. For example, opening a phone accessed through a comm port and modem should result in opening the comm port, making it no longer available for use by other applications.

If the function succeeds, both TAPI and the service provider become committed to operating under the specified interface version number for this open device. Subsquent operations and events identified using the exchanged opaque phone handles conform to that interface version. This commitment and the validity of the handles remain in effect until TAPI closes the phone using TSPI_phoneClose or until the service provider reports the PHONE_CLOSE event. If the function is not successful, no such commitment is made and the handles are not valid.

See Also

PHONE_CLOSE, PHONEEVENT, TSPI_phoneClose, TSPI_phoneNegotiateTSPIVersion


TSPI_phoneSelectExtVersion

The TSPI_phoneSelectExtVersion function selects the indicated extension version for the indicated phone device. Subsequent requests operate according to that extension version.

LONG TSPI_phoneSelectExtVersion(
  HDRVPHONE hdPhone,
  DWORD dwExtVersion
);

Parameters

hdPhone
The handle to the phone for which an extension version is to be selected.
dwExtVersion
The extension version to be selected. This version number is negotiated using TSPI_phoneNegotiateExtVersion. The most-significant WORD is the major version number and the least-significant WORD is the minor version number. Calling this function with a dwExtVersion of zero cancels the current selection.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_RESOURCEUNAVAIL.

Remarks

This function selects the indicated extension version. Although the indicated version number may have been successfully negotiated, a different extension version may have been selected in the interim, in which case this function fails (returning PHONEERR_INCOMPATIBLEEXTVERSION).

Subsequent operations on the phone after an extension version is selected behave according to that extension version. Subsequent attempts to negotiate the extension version report strictly the selected version or zero (if the requested range does not include the selected version). Calling this procedure with the special extension version 0 cancels the current selection. The device once again becomes capable of supporting its full range of extension version numbers.

TSPI_phoneSelectExtVersion is typically called in two situations: (1) An application requested to open a phone, the application requested that a particular extension version be used, and no extension version was currently selected; or (2) the last application using a particular extension version closed the phone, and the extension version selection can be canceled.

See Also

TSPI_phoneNegotiateExtVersion


TSPI_phoneSetButtonInfo

The TSPI_phoneSetButtonInfo function sets information about the specified button on the specified phone.

LONG TSPI_phoneSetButtonInfo(
  DRV_REQUESTID dwRequestID,
  HDRVPHONE hdPhone,
  DWORD dwButtonLampID,
  LPPHONEBUTTONINFO const lpButtonInfo
);

Parameters

dwRequestID
The identifier of the asynchronous request. The service provider returns this value if the function completes asynchronously.
hdPhone
The handle to the phone for which button info is to be set.
dwButtonLampID
A button on the phone device.
lpButtonInfo
A pointer to a variably sized structure of type PHONEBUTTONINFO. This data structure describes the mode and function, and provides additional descriptive text to be set for the button.

Return Values

Returns the (positive) dwRequestID value if the function is completed asynchronously, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or it is an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALBUTTONLAMPID, PHONEERR_OPERATIONFAILED, PHONEERR_NOMEM, PHONEERR_OPERATIONUNAVAIL.

Remarks

This function sets the meaning and associated descriptive text of a phone's buttons.

See Also

ASYNC_COMPLETION, PHONEBUTTONINFO, PHONECAPS, TSPI_phoneGetButtonInfo


TSPI_phoneSetData

The TSPI_phoneSetData function downloads the information in the specified buffer to the opened phone device at the selected data identifier.

LONG TSPI_phoneSetData(
  DRV_REQUESTID dwRequestID,
  HDRVPHONE hdPhone,
  DWORD dwDataID,
  LPVOID const lpData,
  DWORD dwSize
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdPhone
The handle to the phone into which data is to be downloaded.
dwDataID
Specifies where in the phone device the buffer is to be downloaded.
lpData
A pointer to the memory location where the data is to be downloaded from.
dwSize
The size of the buffer in bytes.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or it is an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALDATAID, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

Remarks

The function downloads a maximum of dwSize bytes from lpData to the phone device. The format of the data, its meaning to the phone device, and the meaning of the data identifier are service-provider specific. The data in the buffer or the selection of a data identifier can act as commands to the phone device.

See Also

ASYNC_COMPLETION, PHONECAPS, TSPI_phoneGetData, TSPI_phoneGetDevCaps


TSPI_phoneSetDisplay

The TSPI_phoneSetDisplay function causes the specified string to be displayed on the specified open phone device.

LONG TSPI_phoneSetDisplay(
  DRV_REQUESTID dwRequestID,
  HDRVPHONE hdPhone,
  DWORD dwRow,
  DWORD dwColumn,
  LPCWSTR lpsDisplay,
  DWORD dwSize
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdPhone
The handle to the phone on which the string is to be displayed.
dwRow
The row on the display where the new text is to be displayed.
dwColumn
The column position on the display where the new text is to be displayed.
lpsDisplay
A pointer to the memory location where the display content is stored. The application stores the display information in the format specified as dwStringFormat in the phone's PHONECAPS structure.
dwSize
The size in bytes of the information pointed to by lpDisplay.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or it is an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPARAM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

Remarks

The specified display information is written to the phone's display, starting at the specified positions. This operation overwrites previously displayed information. If the amount of information exceeds the size of the display, the information is truncated. The amount of information that can be displayed is at most (dwNumRows * dwNumColumns) elements in size. The dwNumRows and dwNumColumns members are available in the PHONECAPS structure returned by TSPI_phoneGetDevCaps; they are zero-based.

See Also

ASYNC_COMPLETION, PHONECAPS, TSPI_phoneGetDevCaps, TSPI_phoneGetDisplay


TSPI_phoneSetGain

The TSPI_phoneSetGain function sets the gain of the microphone of the specified hookswitch device to the specified gain level.

LONG TSPI_phoneSetGain(
  DRV_REQUESTID dwRequestID,
  HDRVPHONE hdPhone,
  DWORD dwHookSwitchDev,
  DWORD dwGain
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdPhone
The handle to the phone containing the hookswitch device whose gain is to be set.
dwHookSwitchDev
The hookswitch device whose microphone's gain is to be set. This parameter can have only a single bit set. Values are:
PHONEHOOKSWITCHDEV_HANDSET
The phone's handset.
PHONEHOOKSWITCHDEV_SPEAKER
The phone's speakerphone or adjunct.
PHONEHOOKSWITCHDEV_HEADSET
The phone's headset.
dwGain
A pointer to a DWORD-sized location containing the desired new gain setting of the device. This is a number in the range from 0x00000000 (silence) through 0x0000FFFF (maximum volume). The actual granularity and quantization of gain settings in this range are service-provider-specific. A value for dwGain that is out of range is clamped by TAPI to the nearest in-range value.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or it is an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

See Also

ASYNC_COMPLETION, PHONECAPS, TSPI_phoneGetDevCaps, TSPI_phoneSetGain


TSPI_phoneSetHookSwitch

The TSPI_phoneSetHookSwitch function sets the hook state of the specified open phone's hookswitch devices to the specified mode. Only the hookswitch state of the hookswitch devices listed is affected.

LONG TSPI_phoneSetHookSwitch(
  DRV_REQUESTID dwRequestID,
  HDRVPHONE hdPhone,
  DWORD dwHookSwitchDevs,
  DWORD dwHookSwitchMode
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdPhone
The handle to the phone containing the hookswitch devices whose modes are to be set.
dwHookSwitchDevs
The device(s) whose hookswitch mode is to be set. This parameter uses the following PHONEHOOKSWITCHDEV_ constants:
PHONEHOOKSWITCHDEV_HANDSET
The phone's handset.
PHONEHOOKSWITCHDEV_SPEAKER
The phone's speakerphone or adjunct.
PHONEHOOKSWITCHDEV_HEADSET
The phone's headset.
dwHookSwitchMode
The hookswitch mode to set. This parameter can have only one of the following PHONEHOOKSWITCHMODE_ bits set:
PHONEHOOKSWITCHMODE_ONHOOK
The device's microphone and speaker are both onhook.
PHONEHOOKSWITCHMODE_MIC
The device's microphone is active, and the speaker is mute.
PHONEHOOKSWITCHMODE_SPEAKER
The device's speaker is active, and the microphone is mute.
PHONEHOOKSWITCHMODE_MICSPEAKER
The device's microphone and speaker are both active.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or it is an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALHOOKSWITCHMODE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONUNAVAIL.

Remarks

The hookswitch mode is changed to the indicated setting for all devices specified. If different settings are desired, this function can be invoked multiple times with a different set of parameters. A PHONE_STATE message is sent to the application after the hookswitch state has changed.

See Also

PHONE_STATE, PHONESTATUS, PHONEHOOKSWITCHDEV_ Constants, PHONEHOOKSWITCHMODE_ Constants, TSPI_phoneGetHookSwitch


TSPI_phoneSetLamp

The TSPI_phoneSetLamp function causes the specified lamp to be set on the specified open phone device in the specified lamp mode.

LONG TSPI_phoneSetLamp(
  DRV_REQUESTID dwRequestID,
  HDRVPHONE hdPhone,
  DWORD dwButtonLampID,
  DWORD dwLampMode
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdPhone
The handle to the phone phone whose lamp is to be set.
dwButtonLampID
The button whose lamp is to be set.
dwLampMode
Specifies how the lamp is to be lit. The dwLampMode parameter can only have one of the following PHONELAMPMODE_ bits set:
PHONELAMPMODE_BROKENFLUTTER
Broken flutter is the superposition of flash and flutter.
PHONELAMPMODE_FLASH
Flash means slow on and off.
PHONELAMPMODE_FLUTTER
Flutter means fast on and off.
PHONELAMPMODE_OFF
The lamp is off.
PHONELAMPMODE_STEADY
The lamp is continuously lit.
PHONELAMPMODE_WINK
The lamp is winking.

Return Values

Returns dwRequestID, or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or it is an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALBUTTONLAMPID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALLAMPMODE, PHONEERR_OPERATIONUNAVAIL.

See Also

ASYNC_COMPLETION, PHONELAMPMODE_ Constants, TSPI_phoneGetDevCaps, TSPI_phoneGetLamp


TSPI_phoneSetRing

The TSPI_phoneSetRing function rings the specified open phone device using the specified ring mode and volume.

LONG TSPI_phoneSetRing(
  DRV_REQUESTID dwRequestID,
  HDRVPHONE hdPhone,
  DWORD dwRingMode,
  DWORD dwVolume
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdPhone
The handle to the phone to be rung.
dwRingMode
The ringing pattern with which to ring the phone. This parameter must be within the range from zero through the value of the dwNumRingModes member in the PHONECAPS structure. If dwNumRingModes is zero, the ring mode of the phone cannot be controlled; if dwNumRingModes is 1, a value of 0 for dwRingMode indicates that the phone should not be rung (silence), and other values from 1 through dwNumRingModes are valid ring modes for the phone device.
dwVolume
The volume level with which the phone is to be rung. This is a number in the range from 0x00000000 (silence) through 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service-provider specific. A value for dwVolume that is out of range is clamped by TAPI to the nearest value in range.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or it is an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALRINGMODE, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

Remarks

The service provider defines the actual audible ringing patterns corresponding to each of the phone's ring modes.

See Also

ASYNC_COMPLETION, PHONECAPS, TSPI_phoneGetDevCaps, TSPI_phoneGetRing


TSPI_phoneSetStatusMessages

The TSPI_phoneSetStatusMessages function causes the service provider to filter status messages that are not currently of interest to any application.

LONG TSPI_phoneSetStatusMessages(
  HDRVPHONE hdPhone,
  DWORD dwPhoneStates,
  DWORD dwButtonModes,
  DWORD dwButtonStates
);

Parameters

hdPhone
The opaque handle to the phone whose state-change monitoring filter is to be set.
dwPhoneStates
Flags that specify the set of phone status changes and events for which TAPI wants to receive notification messages. This parameter can have zero, one, or more than one of the following PHONESTATE_ bits set:
PHONESTATE_OTHER
A phone status information item other than those listed below has changed.
PHONESTATE_CONNECTED
The connection between the phone device and the service provider was just made. This happens when the API is first invoked, or when the wire connecting the phone to the computer is plugged in with the API active.
PHONESTATE_DISCONNECTED
The connection between the phone device and the service provider was just broken. This happens when the wire connecting the phone set to the computer is unplugged while the service provider is active.
PHONESTATE_DISPLAY
The display of the phone has changed.
PHONESTATE_LAMP
A lamp of the phone has changed.
PHONESTATE_RINGMODE
The ring mode of the phone has changed.
PHONESTATE_RINGVOLUME
The ring volume of the phone has changed.
PHONESTATE_HANDSETHOOKSWITCH
The handset's hookswitch state has changed.
PHONESTATE_HANDSETVOLUME
The handset's speaker volume setting has changed.
PHONESTATE_HANDSETGAIN
The handset's microphone gain setting has changed.
PHONESTATE_SPEAKERHOOKSWITCH
The speakerphone's hookswitch state has changed.
PHONESTATE_SPEAKERVOLUME
The speakerphone's speaker volume setting has changed.
PHONESTATE_SPEAKERGAIN
The speakerphone's microphone gain setting state has changed.
PHONESTATE_HEADSETHOOKSWITCH
The headset's hookswitch state has changed.
PHONESTATE_HEADSETVOLUME
The headset's speaker volume setting has changed.
PHONESTATE_HEADSETGAIN
The headset's microphone gain setting has changed.
PHONESTATE_SUSPEND
TAPI's use of the phone is temporarily suspended. This can occur when the switch requires exclusive use of the phone device.
PHONESTATE_RESUME
TAPI's use of the phone device is resumed after having been suspended for some time.
PHONESTATE_DEVSPECIFIC
The phone's device-specific information has changed.
PHONESTATE_REINIT
Items have changed in the configuration of phone devices. To become aware of these changes, (as with the appearance of new phone devices) the application should reinitialize its use of TAPI. If specified, the htPhone parameter is left NULL for this state change as it applies to any of the phones in the system.

The PHONESTATE_REINIT message is never masked. REINIT messages should always be sent when appropriate, regardless of the setting of this flag. The setting of the REINIT flag is simply ignored and generates no error.

dwButtonModes
Flags that specify the set of phone button modes for which TAPI wants to receive notification messages. If dwButtonModes is zero, dwButtonStates is ignored. This parameter can have zero, one, or more than one of the following PHONEBUTTONMODE_ bits set. If dwButtonModes has at least one of these flags set, dwButtonStates must also have at least one bit set:
PHONEBUTTONMODE_CALL
The button is assigned to a call appearance.
PHONEBUTTONMODE_FEATURE
The button is assigned to requesting features from the switch, such as hold, conference, or transfer.
PHONEBUTTONMODE_KEYPAD
The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'.
PHONEBUTTONMODE_LOCAL
The button is a local function button, such as mute or volume control.
PHONEBUTTONMODE_DISPLAY
The button is a soft button associated with the phone's display. A phone set can have zero or more display buttons.
dwButtonStates
This parameter specifies the set of phone button state changes for which TAPI wishes to receive notification messages. Values are:
PHONEBUTTONSTATE_UP
The button is in the up state.
PHONEBUTTONSTATE_DOWN
The button is in the down state (pressed down).

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_NOMEM, PHONEERR_INVALPHONESTATE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALBUTTONMODE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALBUTTONSTATE, PHONEERR_OPERATIONUNAVAIL.

Remarks

TAPI defines a number of messages that notify applications about events occurring on phones. The sets of all change messages in which all applications are interested can be much smaller than the set of possible messages. This procedure allows TAPI to tell the service provider the reduced set of messages to deliver. The service provider delivers all of the messages it supports, within the specified set. It is permitted to deliver more (they are filtered out by TAPI), but is discouraged from doing so for performance reasons. If TAPI requests delivery of a particular message type that is not produced by the provider, the provider nevertheless accepts the request but simply does not produce the message. All phone status messages except PHONESTATE_REINIT are disabled by default.

See Also

PHONE_BUTTON, PHONE_STATE, PHONESTATE_ Constants


TSPI_phoneSetVolume

The TSPI_phoneSetVolume function sets the volume of the speaker component of the specified hookswitch device to the specified level.

LONG TSPI_phoneSetVolume(
  DRV_REQUESTID dwRequestID,
  HDRVPHONE hdPhone,
  DWORD dwHookSwitchDev,
  DWORD dwVolume
);

Parameters

dwRequestID
The identifier of the asynchronous request.
hdPhone
The handle to the phone containing the speaker whose volume is to be set.
dwHookSwitchDev
Identifies the hookswitch device whose speaker's volume is to be set. This parameter uses the following PHONEHOOKSWITCHDEV_ constants:
PHONEHOOKSWITCHDEV_HANDSET
The phone's handset.
PHONEHOOKSWITCHDEV_SPEAKER
The phone's speakerphone or adjunct.
PHONEHOOKSWITCHDEV_HEADSET
The phone's headset.
dwVolume
A DWORD specifying the new volume level of the hookswitch device. This is a number in the range from 0x00000000 (silence) through 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service-provider specific. A value for dwVolume that is out of range is clamped by TAPI to the nearest value in range.

Return Values

Returns dwRequestID or an error number if an error occurs. The lResult actual parameter of the corresponding ASYNC_COMPLETION is zero if the function succeeds or it is an error number if an error occurs. Possible return values are as follows:

PHONEERR_INVALPHONEHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPHONESTATE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALHOOKSWITCHDEV, PHONEERR_OPERATIONUNAVAIL, PHONEERR_NOMEM.

Remarks

None.

See Also

ASYNC_COMPLETION, PHONECAPS, PHONEHOOKSWITCHDEV_ Constants, TSPI_phoneGetDevCaps, TSPI_phoneSetVolume


TSPI Callback Functions

Following are descriptions of the Telephony SPI callback functions.


ASYNC_COMPLETION

This type is a callback function implemented by TAPI and supplied to the service provider as a parameter to TSPI_providerInit. The service provider calls this function to report the completion of a line or phone procedure that it executes asynchronously.

ASYNC_COMPLETION Completion_Proc;
void(
  CALLBACK* Completion_Proc)(
  DRV_REQUESTID dwRequestID,
  LONG lResult
);

Parameters

dwRequestID
The identifier passed in the original request that the service provider executed asynchronously.
lResult
The outcome of the operation. This can be zero to indicate success or a negative number to indicate an error. The possible specific error values that can result from a function are the same for asynchronous or synchronous execution.

Return Values

No return value.

Remarks

The call state when calling this function can be any state.

This procedure is supplied by TAPI at the time a service provider is initialized with the TSPI_providerInit function. Some of the TSPI procedures that operate on line, call, and phone devices specify asynchronous operation. These procedures include a dwRequestID parameter to identify the request. When such a procedure is called, the service provider can return a negative number for an error if one is detected immediately, or the positive dwRequestID if the operation continues asynchronously. The service provider must report completion exactly once for each request it executes asynchronously. It does so by calling this procedure. The service provider is not permitted to call this procedure or the LINEEVENT or PHONEEVENT procedure again until this procedure returns.

The service provider is permitted to call the ASYNC_COMPLETION function before it returns from the first request. TAPI guarantees not to call the service provider from within the ASYNC_COMPLETION context except where noted.

This does not have any direct correspondence at the TAPI level because at that level asynchronous function completions are reported as a message passed through the same callback interface that is used for spontaneous event messages. At the TSPI level, spontaneous events are reported through the LINEEVENT and PHONEEVENT callback procedures.

See Also

LINEEVENT, PHONEEVENT, TSPI_providerInit


LINEEVENT

This type is a callback function implemented by TAPI and supplied to the service provider as a parameter to TSPI_lineOpen. The service provider calls this function to report events that occur on the line or on calls on the line.

LINEEVENT Line_Event;
void(
  CALLBACK * Line_Event)(
  HTAPILINE htLine,
  HTAPICALL htCall,
  DWORD dwMsg,
  DWORD dwParam1,
  DWORD dwParam2,
  DWORD dwParam3
);

Parameters

htLine
The TAPI handle for the line on which the event occurred.
htCall
The TAPI handle for the call on which the event occurred if this is a call-related event. For line-related events where there is no call, this parameter is set to NULL.
dwMsg
Specifies the kind of event that is being reported. Interpretation of the other parameters is performed in different ways according to the context indicated by dwMsg.
dwParam1
A parameter for the message.
dwParam2
A parameter for the message.
dwParam3
A parameter for the message.

Return Values

No return value.

Remarks

The call state when calling this function can be any state.

The service provider passes the HTAPILINE value supplied to TSPI_lineOpen as the htLine parameter. It includes the message identifier and parameters specific to the event.

This function differs from the callback function defined at the TAPI level in that it separates line and call parameters. Both parameters are used for some messages. The sets of messages that can be passed to this procedure differ slightly from the TAPI level. In particular, completion of asynchronously executing requests is reported through the ASYNC_COMPLETION callback instead of this one.

See Also

ASYNC_COMPLETION, TSPI_lineOpen


PHONEEVENT

This type is a callback function implemented by TAPI and supplied to the service provider as a parameter to TSPI_phoneOpen The service provider calls this function to report events that occur on the phone.

PHONEEVENT Phone_Event;
void(
  CALLBACK *Phone_Event)(
  HTAPIPHONE htPhone,
  DWORD dwMsg,
  DWORD dwParam1,
  DWORD dwParam2,
  DWORD dwParam3
);

Parameters

htPhone
The TAPI handle for the phone on which the event occurred.
dwMsg
Specifies the kind of event that is being reported. Interpretation of the other parameters is done in different ways according to the context indicated by dwMsg.
dwParam1
A parameter for the message.
dwParam2
A parameter for the message.
dwParam3
A parameter for the message.

Return Values

No return value.

Remarks

The call state when calling this function can be any state.

The service provider passes the HTAPIPHONE value supplied to TSPI_phoneOpen as the htPhone parameter. It includes the message identifier and parameters specific to the event.

The sets of messages that can be passed to this procedure differ slightly from the messages to the corresponding callback at the TAPI level. In particular, completion of asynchronously executing requests is reported through the ASYNC_COMPLETION callback instead of this one.

See Also

ASYNC_COMPLETION, TSPI_lineOpen


The Telephony Service Provider UI DLL Interface

In Win32 Telephony, telephony service providers execute in a separate process from telephony applications. Service providers communicate with tapisrv.exe through the Telephony service provider interface (TSPI) and execute in its process; applications interface to TAPI32.DLL, which are loaded in the application context.

The components of TAPI use various interprocess communications mechanisms to convey function requests and messages between applications and service providers. The applications and the service providers may be executing not only in separate processes, but on completely separate systems. Service providers therefore cannot display dialog boxes in the process or even on the computer on which they are executing; UI must be invoked from within the application context, on the computer on which the application is executing.

This section defines the mechanism by which service provider UI functions are loaded and invoked within the application context. A mechanism is also defined by which service providers can spontaneously open dialog boxes in the application context when they would not otherwise be expected by the application. An example of this latter case would be the Talk/Hangup dialog box that is displayed by a data modem service provider when the modem is being used as a dialer for interactive voice calls, and the user must be told to pick up the phone and inform the service provider when to place the modem onhook.


Architecture

The following illustration shows the general architecture of telephony service providers and their associated user interface dynamic-link libraries (UI DLLs).

The service provider consists of a minimum of two components. The service provider DLL (designated in the illustration as MAIN.TSP) executes in the context of the tapisrv.exe process, and performs all of the tasks of the service provider that are not related to user interface elements associated with a particular application's use of the device (most likely, in conjunction with lower-level components not shown in the illustration). But unlike previous versions of TAPI in which the user interface code was integrated into the service provider (and executed, because of the previous architecture, within the context of the application), the service provider must now include a separate component that implements the user interface elements.

The service provider UI DLL must be a Win32 (32-bit) DLL. It must export functions that are called by TAPI when the application calls TAPI functions that generate UI: TUISPI_lineConfigDialog, TUISPI_lineConfigDialogEdit, TUISPI_phoneConfigDialog, TUISPI_providerConfig, TUISPI_providerInstall, and TUISPI_providerRemove. Each of these functions includes as a parameter a pointer to a callback function in TAPI, of type TUISPIDLLCALLBACK, which the UI DLL can use to communicate bidirectionally (both send and receive data) with the service provider DLL executing in the TAPISRV process. If the service provider ever generates spontaneous UI, such as the Unimodem Talk/Hangup dialog box, in conjunction with any TSPI function for which UI is not expected (for example, any function that does not have an hwnd parameter), then the UI DLL must export TUISPI_providerGenericDialog and TUISPI_providerGenericDialogData.

Note The original TSPI UI-generating functions (TSPI_lineConfigDialog, TSPI_lineConfigDialogEdit, TSPI_phoneConfigDialog, TSPI_providerConfig, TSPI_providerInstall, and TSPI_providerRemove) are obsolete and never called by TAPI. Therefore, these are not required to be exported by the service provider DLL. However, if the service provider wants to be listed as one that can be added by the Telephony Control Panel, a utility supplied with Windows Telephony in versions 1.4 and earlier, it must export TSPI_providerInstall; if it wants to have the Remove button enabled in the Telephony Control Panel when it is selected, it must export TSPI_providerRemove; and if it wants the Setup button to be enabled in the Telephony Control Panel when it is selected, it must export TSPI_providerConfig. The Telephony Control Panel checks for the presence of these functions in the service provider TSP file to adjust its user interface to reflect which operations can be performed.

The service provider DLL must export the TSPI_providerUIIdentify function that tapisrv.exe process uses to obtain the name of the UI DLL to load in the application process. It must export the TSPI_providerGenericDialogData function to receive and respond to requests from the UI DLL for data to display, and it must export TSPI_providerFreeDialogInstance for tapisrv.exe process to tell the service provider when to release an association established for the purpose of generating spontaneous UI in conjunction with a function that is not defined as presenting UI to the user. The service provider DLL can unidirectionally send data to the UI DLL by using the new TSPI message LINE_SENDDIALOGINSTANCEDATA.

Because the names of the TSPI and TUISPI functions are intentionally defined to be different, the service provider DLL and the UI DLL can be the same DLL file, if desired. With proper segmentation, this does not necessarily result in any unnecessary usage of memory in the application context, and can simplify the installation process for service providers that can currently be implemented in a single DLL. TAPI calls only the functions that are appropriate for the context in which the DLL is being used.

The telephony service provider and the UI DLL must both be designed with the requirement in mind that the UI functions can be invoked from multiple application processes simultaneously. They must also consider that the application and the TAPI service under which the telephony service provider is executing can be on separate computers on a LAN.


Usage

There are two general cases of usage of the TSP UI DLL interface: when the application invokes a function that is designed to generate UI, and when the service provider must spontaneously generate UI in the course of processing a function that is not defined as generating UI.


Functions Designed to Generate UI

Assume for the purposes of an example that the application calls the TAPI lineConfigDialog function, which is designed to open a dialog box to allow configuration of service provider options related to the specified line device. In response to this call, TAPI requests TAPISRV to call TSPI_providerUIIdentify in the telephony service provider, obtaining the name of the TSP UI DLL.

In the application's context, TAPI loads the TSP UI DLL and calls the TUISPI_lineConfigDialog function with the parameters supplied by the application, and including a pointer to the TAPI TUISPIDLLCALLBACK function. The TSP UI DLL displays the configuration dialog box, calling the TUISPIDLLCALLBACK function as necessary to obtain from the telephony service provider the information to display. Each time the TUISPIDLLCALLBACK function is called, TAPI requests TAPISRV to call the telephony service provider's TSPI_providerGenericDialogData function, passing in the parameter block from the UI DLL, and returning the parameter block to the UI DLL. The UI DLL conveys any configuration changes to the telephony service provider by calling TUISPIDLLCALLBACK.

When the function is complete, the UI DLL returns from (in this case) TUISPI_lineConfigDialog. TAPI calls the Win32 FreeLibrary function to release the UI DLL, and returns to the application.


Functions Not Designed to Generate UI

Assume that the service provider must display a dialog box (like the Unimodem or ATSP Talk/Hangup dialog box) during the processing of lineMakeCall or lineDial. In this case, it is the service provider, not the application, that decides that UI must be displayed.

To invoke the UI DLL in the application process, the service provider calls the TSPI LINEEVENT callback, generating a LINE_CREATEDIALOGINSTANCE message, passing in a pointer to a structure of type TUISPICREATEDIALOGINSTANCEPARAMS. This structure contains the dwRequestID of the function with which the UI is associated, allowing TAPISRV to identify the client application in which the UI is to be generated.

TAPISRV requests the correct application's instance of TAPI to load the UI DLL and create a thread for the UI within the application's process. From this new UI thread, TAPI calls the UI DLL's TUISPI_providerGenericDialog function, passing in data that was specified by the telephony service provider in the structure passed in with the LINE_CREATEDIALOGINSTANCE message; the UI DLL displays the appropriate dialog box (which is a matter for private design between the UI DLL and the telephony service provider). The UI DLL does not return from TUISPI_providerGenericDialog until the dialog box is closed.

The telephony service provider can generate updated data to display in the dialog box (or, for example, instruct the dialog box to be closed, if the call is abandoned or other events occur) by sending a LINE_SENDDIALOGINSTANCEDATA message. TAPISRV conveys the data to TAPI, which calls the UI DLL's TUISPI_providerGenericDialogData function. This mechanism provides a unidirectional "send" to the UI DLL. If the UI DLL wants to inform the telephony service provider of the results of the dialog box or obtain other data, it can call the TUISPIDLLCALLBACK function (a pointer to which it received when TUISPI_providerGenericDialog was called).

When the dialog box is dismissed, TUISPI_providerGenericDialog returns to TAPI. TAPI calls FreeLibrary to release the UI DLL, and exits the UI thread it had created in the application context. It then requests TAPISRV to call the telephony service provider's TSPI_providerFreeDialogInstance function to unbind the association created when the telephony service provider originally sent the LINE_CREATEDIALOGINSTANCE message. This function is also called if the application process terminates unexpectedly before TUISPI_providerGenericDialog returns.


TSP UI DLL Functions

The following topics describe the Telephony Service Provider User Interface (UI) DLL functions.


TSPI_providerFreeDialogInstance

The TSPI_providerFreeDialogInstance function informs the service provider that the dialog box associated with hdDlgInst has exited. After this function is called, the service provider should no longer send data to the dialog box using LINE_SENDDIALOGINSTANCEDATA messages.

Implementation of this function is optional; it is needed only if the service provider generates spontaneous dialog boxes in application contexts using LINE_CREATEDIALOGINSTANCE.

LONG TSPIAPI TSPI_providerFreeDialogInstance(
  HDRVDIALOGINSTANCE hdDlgInst
);

Parameters

hdDlgInst
The opaque identifier of the association between the service provider and the dialog box in the application's context, which was passed as the hdDlgInstance member in the TUISPICREATEDIALOGINSTANCEPARAMS structure with the LINE_CREATEDIALOGINSTANCE message that created the dialog box.

Return Values

Returns zero if successful, or one of these negative error values:

LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONFAILED.

See Also

LINE_CREATEDIALOGINSTANCE, LINE_SENDDIALOGINSTANCEDATA, TUISPICREATEDIALOGINSTANCEPARAMS


TSPI_providerGenericDialogData

The TSPI_providerGenericDialogData function delivers to the service provider data that was sent from the UI DLL running in an application context through the TUISPIDLLCALLBACK function. The contents of the memory block pointed to by lpParams is defined by the service provider and UI DLL. The service provider can modify the contents of the parameter block; when this function returns, TAPI copies the modified data back into the original UI DLL parameter block.

Implementation is mandatory if the UI DLL associated with the service provider calls TUISPIDLLCALLBACK.

LONG TSPIAPI TSPI_providerGenericDialogData(
  DWORD dwObjectID,
  DWORD dwObjectType,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

dwObjectID
An object identifer of the type specified by dwObjectType
dwObjectType
One of the TUISPIDLL_OBJECT_ constants, specifying the type of object identified by dwObjectID
TUISPIDLL_OBJECT_LINEID
dwObjectID is a line device identifier (dwDeviceID).
TUISPIDLL_OBJECT_PHONEID
dwObjectID is a phone device identifier (dwDeviceID)
TUISPIDLL_OBJECT_PROVIDERID
dwObjectID is a permament provider identifier.
TUISPIDLL_OBJECT_DIALOGINSTANCE
dwObjectID is an HDRVDIALOGINSTANCE, as returned to the service provider when it sent a LINE_CREATEDIALOGINSTANCE message.
lpParams
Pointer to a memory area used to hold a parameter block. The contents of this parameter block are specific to the service provider and its associated UI DLL.
dwSize
The size in bytes of the parameter block.

Return Values

Returns zero if successful, or one of these negative error values:

LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONFAILED.

See Also

LINE_CREATEDIALOGINSTANCE, TUISPIDLLCALLBACK


TSPI_providerUIIdentify

The TSPI_providerUIIdentify function extracts from the service provider the fully qualified path to load the service provider's UI DLL component.

Implementation is mandatory if the service provider implements any UI DLL functions.

LONG TSPIAPI TSPI_providerUIIdentify(
  LPWSTR lpszUIDLLName
);

Parameters

lpszUIDLLName
Pointer to a block of memory at least MAX_PATH in length, into which the service provider must copy a NULL-terminated string specifying the fully-qualified path for the DLL containing the service provider functions which must execute in the process of the calling application.

Return Values

Returns zero if successful. Shouldn't ever fail, but if it does returns one of these negative error values:

LINEERR_NOMEM, LINEERR_OPERATIONFAILED.


TUISPI Service Provider Functions

This section contains an alphabetic list of the TUISPI service provider functions.


TUISPI_providerConfig

The TUISPI_providerConfig function implements the UI elements that must execute in the context of the calling application. This function makes the TSPI_providerConfig function obsolete in version 2.0 and later (supported in version 1.4 and earlier).

The TUISPI_providerConfig function gathers configuration information from the user. It can use a dialog box, and this dialog box can include sub-dialog boxes associated with other APIs (such as Comm/datamodem) for the setup of specific devices.

Implementation is optional.

LONG TSPIAPI TUISPI_providerConfig(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  HWND hwndOwner,
  DWORD dwPermanentProviderID
);

Parameters

lpfnUIDLLCallback
Pointer to a function the UI DLL can call to communicate with the service provider DLL to obtain information needed to display the dialog box and to send updated configuration to the service provider.
hwndOwner
The handle of the parent window in which the function can create any dialog box windows required during the configuration.
dwPermanentProviderID
The service provider's permanent provider identifier.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_OPERATIONFAILED, LINEERR_NOMEM.

Remarks

This function may be called while the service provider is in use (that is, between calls of TSPI_providerInit and TSPI_providerShutdown).

Any changes that affect the behavior visible through TSPI should take effect only when the service provider is restarted at the next TSPI_providerInit.

There is no directly corresponding function at the TAPI level. In TAPI, applications have access to the functions lineConfigDialog and phoneConfigDialog, which allow configuration of parameters of a particular line or phone once it has been installed.

See Also

TUISPI_lineConfigDialog, TUISPI_phoneConfigDialog, TUISPI_providerInstall, TUISPI_providerRemove


TUISPI_providerGenericDialog

The TUISPI_providerGenericDialog function in the UI DLL is called when the service provider sends a LINE_CREATEDIALOGINSTANCE message. The service provider uses this to create dialog boxes in the application context in conjunction with the processing of particular asynchronous TSPI functions. This function is called from a thread created specifically for the purpose of displaying the dialog box. The UI DLL does not return from this function until the dialog box is destroyed.

Implementation is mandatory if the service provider associated with the UI DLL sends LINE_CREATEDIALOGINSTANCE messages to spontaneously create dialog boxes in the application context.

LONG TSPIAPI TUISPI_providerGenericDialog(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  HTAPIDIALOGINSTANCE htDlgInst,
  LPVOID lpParams,
  DWORD dwSize,
  HANDLE hEvent
);

Parameters

lpfnUIDLLCallback
Pointer to a function the UI DLL can call to communicate with the service provider DLL to obtain information needed to display the dialog box.
htDlgInst
The opaque identifier binding the association of this instance of the function to a particular request from the service provider. The UI DLL must include this parameter, along with TUISPI_OBJECT_DIALOGINSTANCE, in any call to TUISPIDLLCALLBACK to request further data from or deliver data to the service provider.
lpParams
Pointer to a memory area used to hold a parameter block. The contents of this parameter block are specific to the service provider and its associated UI DLL. The conveyance of data through this parameter block is one-way to the UI DLL; changes made to the parameter block are not reflected back in the service provider. Generally, this parameter block holds all information the UI DLL needs to initially display the dialog box.
dwSize
The size in bytes of the parameter block.
hEvent
Handle to an event object created by TAPI. This event is signaled by the UI DLL through SetEvent(hEvent) when the UI DLL has completed initialization of this dialog box instance and is prepared to receive additional dialog box data through TUISPI_providerGenericDialogData. Data sent by the associated service provider (through LINE_SENDDIALOGINSTANCEDATA) for this dialog box instance are blocked by TAPI until the UI DLL signals this event, giving TUISPI_providerGenericDialog the opportunity to perform any necessary initialization. The UI DLL should signal the event as quickly a possible to avoid blocking calls to TUISPI_providerGenericDialogData.

Return Values

Returns zero if successful, or one of these negative error values:

LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONFAILED.


TUISPI_providerGenericDialogData

The TUISPI_providerGenericDialogData function in the UI DLL is called when the service provider sends a LINE_SENDDIALOGINSTANCEDATA message. The service provider uses this to spontaneously update information in dialog boxes created in the application context in conjunction with the processing of particular asynchronous TSPI functions. This function is called from a separate thread from that in which TSPI_providerGenericDialog is executing. The UI DLL should not block the thread in which this function is called, but should process the data and return immediately (posting a message to the dialog box if necessary).

Implementation is mandatory if TUISPI_providerGenericDialog is exported.

LONG TSPIAPI TUISPI_providerGenericDialog(
  HTAPIDIALOGINSTANCE htDlgInst,
  LPVOID lpParams,
  DWORD dwSize
);

Parameters

htDlgInst
The opaque identifier binding the association of this instance of the function to a particular request from the service provider.
lpParams
Pointer to a memory area used to hold a parameter block. The contents of this parameter block are specific to the service provider and its associated UI DLL. The conveyance of data through this parameter block is one-way to the UI DLL; changes made to the parameter block are not reflected back in the service provider. If this parameter is set to NULL, this is a request to close the dialog box immediately and clean up (TUISPIDLLCALLBACK should not be invoked during this cleanup). TAPI invokes this function with lpParams set to NULL to force dialog box cleanup under certain circumstances, such as an application calling lineShutdown with a dialog box still active.
dwSize
The size in bytes of the parameter block.

Return Values

Returns zero if successful, or one of these negative error values:

LINEERR_INVALPARAM, LINEERR_NOMEM, LINEERR_OPERATIONFAILED.


TUISPI_providerInstall

Implementation of the TUISPI_providerInstall function is the service provider's opportunity to install any additional "pieces" of the provider into the right directories (or at least verifying that they're there) and set up registry entries the provider needs. This function makes the TSPI_providerInstall function obsolete in version 2.0 and later (supported in version 1.4 and earlier).

If the service provider requires any privately-defined entries in the registry for proper operation, they must be installed at this time.

Implementation is optional.

LONG TSPIAPI TUISPI_providerInstall(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  HWND hwndOwner,
  DWORD dwPermanentProviderID
);

Parameters

lpfnUIDLLCallback
Pointer to a function the UI DLL can call to communicate with the service provider DLL to obtain information needed to display the dialog box.
hwndOwner
The handle of the parent window in which the function can create any dialog box windows that are required during installation.
dwPermanentProviderID
The service provider's permanent provider identifier.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_NOMEM. LINEERR_INVALPARAM.

Remarks

This function must leave the system in a consistent state. It should run to completion, not allowing the user to abort the installation when it is partly completed. If installation fails, it is the provider's responsibility to "back out" what was done and return an error. This may imply pre-scanning to verify that a complete installation is possible, before the installation begins.

This function can be invoked more than once during installation of the service provider, until there is a call to TUISPI_providerRemove. If the service provider does not require or support multiple instances of the provider, however, it returns the LINEERR_ Constants LINEERR_NOMULTIPLEINSTANCE.

The corresponding function at the TAPI level is lineAddProvider. The LINE_CREATE message informs applications that are running about dynamic reconfiguration.

See Also

LINE_CREATE, PHONE_STATE, TUISPI_providerConfig, TSPI_providerInit, TUISPI_providerRemove, TSPI_providerShutdown


TUISPI_providerRemove

The TUISPI_providerRemove function asks the user to confirm elimination of the service provider. This function makes the TSPI_providerRemove function obsolete in version 2.0 and later (supported in version 1.4 and earlier).

It is the responsibility of the service provider to remove any registry entries that the service provider added at addProvider time, as well as any other modules and files that are no longer needed.

Implementation is optional.

LONG TSPIAPI TUISPI_providerRemove(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  HWND hwndOwner,
  DWORD dwPermanentProviderID
);

Parameters

lpfnUIDLLCallback
Pointer to a function the UI DLL can call to communicate with the service provider DLL to obtain information needed to display the dialog box.
hwndOwner
The handle of the parent window in which the function can create any dialog box windows required during the removal.
dwPermanentProviderID
The service provider's permanent provider identifier.

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM.

Remarks

This function must guarantee that any service provider's privately-defined information is removed from the registry if it returns success.

This procedure must leave the system in a consistent state. It should run to completion, not allowing the user to abort the removal when it is partly completed. If removal fails, it is the provider's responsibility to "back out" what was done and return an error. This may imply pre-scanning to verify that a complete removal is possible, before the removal begins.

This function can be called while the service provider is in use (that is, between TSPI_providerInit and TSPI_providerShutdown). If this happens, the service provider should do an appropriate combination of displaying a user dialog box to announce any conflict and confirm removal, restricting removal options to those that can be performed transparently, or issuing LINE_CLOSE and PHONE_CLOSE messages to inform TAPI and applications that the affected devices have been forcibly closed for removal. In any case, any changes that affect the behavior visible through TSPI should take effect only when the service provider is shut down at the next TSPI_providerShutdown.

Note This function should not return LINEERR_INUSE or other errors that might occur because the provider is in use by an application; instead, the provider should confer with the user directly about this problem, and then return LINEERR_OPERATIONFAILED if the user decides to abort the operation.

This procedure is called only once, at the time of removal of the service provider, until there is a call to TUISPI_providerInstall.

The corresponding function at the TAPI level is lineRemoveProvider. At that level, applications expect to have service providers already installed; otherwise their lines and phones do not appear within the available sequence of device identifiers. The LINE_CREATE message informs applications that are running about dynamic reconfiguration.

See Also

LINE_CLOSE, PHONE_CLOSE, PHONE_STATE, TSPI_providerInit, TSPI_providerShutdown, TUISPI_providerInstall


TUISPI Line Device Functions

This section contains an alphabetic list of the TUISPI line device functions.


TUISPI_lineConfigDialog

The TUISPI_lineConfigDialog function causes the provider of the specified line device to display a modal dialog box as a child window of hwndOwner to allow the user to configure parameters related to the line device. This function makes the TSPI_lineConfigDialog function obsolete in version 2.0 and later (supported in version 1.4 and earlier).

Implementation is optional.

LONG TSPIAPI TUISPI_lineConfigDialog(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  DWORD dwDeviceID,
  HWND hwndOwner,
  LPCWSTR lpszDeviceClass
);

Parameters

lpfnUIDLLCallback
Pointer to a function the UI DLL can call to communicate with the service provider DLL to obtain information needed to display the dialog box and to send updated configuration to the service provider.
dwDeviceID
The line device to be configured.
hwndOwner
A handle to a parent window in which the dialog box window is to be placed.
lpszDeviceClass
A pointer to a NULL-terminated string that identifies a device class name. This device class allows the caller to select a specific subscreen of configuration information applicable to that device class. If this parameter is NULL or an empty string, the highest level configuration dialog box should be selected. The permitted strings are the same as for TSPI_lineGetID. For example, if the line supports the Comm API, passing comm/datamodem as lpszDeviceClass causes the provider to display the parameters related specifically to Comm (or, at least, to start at the corresponding point in a multilevel configuration dialog box chain, so that the user doesn't have to search to find the desired parameters.)

Return Values

Returns zero if the function succeeds or an error number if an error occurs. Possible return values are as follows:

LINEERR_INUSE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

There is no restriction that TUISPI_lineConfigDialog be called only when the line is closed. However, each provider can impose such a restriction itself. When TUISPI_lineConfigDialog is called, the provider could alert the user with the message "The line is in use by one or more applications. You may not change the line configuration while the line is in use" (and return the error message LINEERR_INUSE). However, some configuration may be safe to change "on the fly," particularly those related to media modes (such as the modem error control protocol), especially when that media mode is not currently in use. The provider could allow those options to be changed while the line is open.

Users should not be allowed to change anything that alters values returned with LINEDEVCAPS or LINEADDRESSCAPS without first forcibly closing the line as a signal that applications must call functions that return these structures in order to have accurate information.

See Also

LINEADDRESSCAPS, LINEDEVCAPS, TSPI_lineGetDevConfig, TSPI_lineGetID, TSPI_lineSetDevConfig


TUISPI_lineConfigDialogEdit

The TUISPI_lineConfigDialogEdit function causes the provider of the specified line device to display a modal dialog box as a child window of hwndOwner to allow the user to configure parameters related to the line device. This function makes the TSPI_lineConfigDialogEdit function obsolete in version 2.0 and later (supported in version 1.4 and earlier).

Implementation is optional.

LONG TSPIAPI TUISPI_lineConfigDialogEdit(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  DWORD dwDeviceID,
  HWND hwndOwner,
  LPCWSTR lpszDeviceClass,
  LPVOID const lpDeviceConfigIn,
  DWORD dwSize,
  LPVARSTRING lpDeviceConfigOut
);

Parameters

lpfnUIDLLCallback
Pointer to a function the UI DLL can call to communicate with the service provider DLL to obtain information needed to display the dialog box.
dwDeviceID
The line device to be configured.
hwndOwner
A handle to a window to which the dialog box is to be attached.
lpszDeviceClass
A pointer to a NULL-terminated string that identifies a device class name. This device class allows the caller to select a specific subscreen of configuration information applicable to that device class. If this parameter is NULL or points to an empty string, the highest level configuration is selected. The permitted strings are the same as for TSPI_lineGetID.
lpDeviceConfigIn
A pointer to the opaque configuration data structure that was returned by TSPI_lineGetDevConfig (or a previous invocation of TUISPI_lineConfigDialogEdit) in the variable portion of the VARSTRING structure.
dwSize
The number of bytes in the structure pointed to by lpDeviceConfigIn. This value is returned in the dwStringSize member in the VARSTRING structure returned by TSPI_lineGetDevConfig or a previous invocation of TUISPI_lineConfigDialogEdit.
lpDeviceConfigOut
A pointer to the memory location of type VARSTRING where the device configuration structure is returned. Upon successful completion of the request, this location is filled with the device configuration. The dwStringFormat member in the VARSTRING structure is set to STRINGFORMAT_BINARY. Prior to calling lineGetDevConfig (or a future invocation of lineConfigDialogEdit), the application should set the dwTotalSize member of this structure to indicate the amount of memory available to TAPI for returning information.

Return Values

Returns zero if the request succeeds or an error number if an error occurs. Possible return values are:

LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM.

Remarks

The lpszDeviceClass parameter selects a specific subscreen of configuration information applicable to the device class in which the user is interested; the permitted strings are the same as for TSPI_lineGetID. For example, if the line supports the Comm API, passing comm/datamodem as lpszDeviceClass causes the provider to display the parameters related specifically to Comm (or, at least, start at the corresponding point in a multilevel configuration dialog box chain, so the user doesn't have to "dig" to find the parameters of interest).

The lpszDeviceClass parameter is "tapi/line" , "", or NULL to cause the provider to display the highest level configuration for the line.

The difference between this function and TUISPI_lineConfigDialog is the source of the parameters to edit and the result of the editing. In TUISPI_lineConfigDialog, the parameters edited are those currently in use on the device (or set for use on the next call), and any changes made have (to the maximum extent possible) an immediate impact on any active connection; also, the application must use lineGetDevConfig to fetch the result of parameter changes from TUISPI_lineConfigDialog. With TUISPI_lineConfigDialogEdit, the parameters to edit are passed in from the application, and the results are returned to the application, with no impact on active connections; the results of the editing are returned with this function, and the application does not need to call lineGetDevConfig. Thus, TUISPI_lineConfigDialogEdit permits an application to provide the ability for the user to set up parameters for future calls without having an impact on any active call. However, the output of this function can be passed to TSPI_lineSetDevConfig to affect the current call or next call.

For backward compatibility, this function is not exported by older service providers. TAPI detects this condition and reports LINEERR_OPERATIONUNAVAIL if an application attempts to call this function on an older provider.

See Also

TSPI_lineGetDevConfig, TSPI_lineGetID, TSPI_lineSetDevConfig, TUISPI_lineConfigDialog, VARSTRING


TUISPI Phone Device Functions

This section contains an alphabetic list of the TUISPI phone device functions.


TUISPI_phoneConfigDialog

The TUISPI_phoneConfigDialog function causes the provider of the specified phone device to display a modal dialog box as a child window of hwndOwner to allow the user to configure parameters related to the phone device.This function makes the TSPI_phoneConfigDialog function obsolete in version 2.0 and later (supported in version 1.4 and earlier).

Implementation is optional.

LONG TSPIAPI TUISPI_phoneConfigDialog(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  DWORD dwDeviceID,
  HWND hwndOwner,
  LPCWSTR lpszDeviceClass
);

Parameters

lpfnUIDLLCallback
Pointer to a function the UI DLL can call to communicate with the service provider DLL to obtain information needed to display the dialog box and to send updated configuration to the service provider.
dwDeviceID
The phone device to be configured.
hwndOwner
A handle to a parent window in which the dialog box window is to be placed.
lpszDeviceClass
A pointer to a NULL-terminated string that identifies a device class name. This device class allows the caller to select a specific subscreen of configuration information applicable to that device class. If this parameter is NULL or an empty string, the highest level configuration dialog box is selected.

Return Values

Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:

PHONEERR_BADDEVICEID, PHONEERR_NOMEM, PHONEERR_INUSE, PHONEERR_OPERATIONFAILED, PHONEERR_INVALPARAM, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALDEVICECLASS, PHONEERR_RESOURCEUNAVAIL.

Remarks

The lpszDeviceClass parameter allows the application to select a specific subscreen of configuration information applicable to the device class in which the user is interested. The permitted strings are the same as for TSPI_phoneGetID.

For example, if the phone supports the Comm API, passing comm/datamodem as lpszDeviceClass causes the provider to display the parameters related specifically to Comm (or, at least, to start at the corresponding point in a multilevel configuration dialog box chain, so that the user doesn't have to search to find the desired parameters). The szDeviceClass parameter should be "tapi/phone", "", or NULL to cause the provider to display the highest level configuration for the phone.

See Also

PHONECAPS, TSPI_phoneGetID


TUISPI Callback Functions

This section contains descriptions of the TUISPI callback functions.


TUISPIDLLCALLBACK

TUISPIDLLCALLBACK is called by the UI DLL to send a private parameter block to the service provider. Each invocation of the callback results in a call to the TSPI_providerGenericDialogData function in the service provider associated with the specified object. The contents of the parameter block are defined by the service provider and UI DLL. The service provider can modify the contents of the parameter block; when this function returns, TAPI copies the modified data back into the original UI DLL parameter block.

typedef LONG (CALLBACK * TUISPIDLLCALLBACK) (
    DWORD dwObjectID,
    DWORD dwObjectType,
    LPVOID lpParams,
    DWORD dwSize);

Parameters

dwObjectID
An object identifer of the type specified by dwObjectType.
dwObjectType
One of the TUISPIDLL_OBJECT_ constants, specifying the type of object identified by dwObjectID.
TUISPIDLL_OBJECT_LINEID
The dwObjectID parameter is a line device identifier (dwDeviceID). This is used when the callback is invoked during the processing of TUISPI_lineConfigDialog or TUISPI_lineConfigDialogEdit.
TUISPIDLL_OBJECT_PHONEID
The dwObjectID parameter is a phone device identifier (dwDeviceID). This is used when the callback is invoked during the processing of TUISPI_phoneConfigDialog.
TUISPIDLL_OBJECT_PROVIDERID
The dwObjectID parameter is a permament provider identifier. This is used when the callback is invoked during the processing of TUISPI_providerConfig, TUISPI_providerInstall, or TUISPI_providerRemove.
TUISPIDLL_OBJECT_DIALOGINSTANCE
The dwObjectID parameter is an HDRVDIALOGINSTANCE, as returned to the service provider when it sent a LINE_CREATEDIALOGINSTANCE message. This is used when the callback is invoked during the processing of TUISPI_providerGenericDialog.
lpParams
Pointer to a memory area used to hold a parameter block.
dwSize
The size in bytes of the parameter block.

Return Values

Returns zero if successful, or one of these negative error values:

LINEERR_INVALPARAM, LINEERR_INVALPOINTER, LINEERR_NOMEM, LINEERR_OPERATIONFAILED.


TSPI Structures

The data structures described in this section are identical to those defined at the TAPI level. The TSPI header file does not define them. It includes them from the TAPI header file. The following sections defining the line-related and phone-related data structures are identical to the corresponding descriptions in the TAPI interface.

In the case of most of the larger data structures, the responsibility for filling in members is divided between the service provider and TAPI. The service provider must preserve the values present in members owned by TAPI. The description of which members must be set by the service provider and which must be preserved is provided in the Functions section in the functions that refer to that data structure.

For each structure, whether it is defined by TSPI or by TAPI, this section lists the following items:

  • The purpose of the structure
  • A description of the values or fields
  • A description of the structure's extensibility
  • Optional comments about using the structure
  • Optional references to other functions, messages, constants, or structures.

Memory for all data structures whose representation is published and shared by both TAPI and the service provider is allocated by TAPI or an application using TAPI. TAPI passes a pointer to the TSPI function that returns the information. TSPI fills the data structure with the requested information. If the operation is asynchronous, the information is not available until the asynchronous reply callback indicates success.

Note Some structures include Size and Offset fields for defining the location and length of strings in the variable portion of the structure. If the service provider is requested to add a string but no string is available, the service provider must indicate this condition in one of these ways:

  • Set both the Size and Offset fields to 0.
  • Set the Offset field to nonzero but Size to 0.
  • Set the Offset field to nonzero, Size to 1, and the byte at the Offset to 0.


Opaque Handles

A few types defined by TSPI are opaque handles. These are used in TSPI as public references to private data structures. This allows type-checking of parameters supplied to the interface procedures while still giving a measure of type protection. Only the owner of the private data structure knows how to interpret the opaque type as a reference to its data structure representation. As an example of how opaque handles are used, consider a phone device. Both TAPI and the service provider typically maintain data structures representing their respective views of the device.

In typical phone data structures maintained by TAPI and a service provider, each contains an opaque handle for the other data structure. These were exchanged at an early initialization step. When TAPI calls a function in the TSPI interface, it passes the opaque handle to refer to the device. The service provider knows how to resolve this as a reference (arrow) to its data structure. A similar process occurs when the service provider calls a callback function in TAPI.


Opaque Handles and Private Data Structures

Opaque handles are used in TSPI to refer to the data structures representing lines, phones, and call appearances. These appear as parameters to most of the functions and callbacks. There are few functions that refer to the device using a device identifier instead of an opaque handle. In such a case, the reference is to the device itself rather than to a data structure. Functions that work in this fashion are typically those called at early initialization times before data structures are created and opaque handles are exchanged.

The service provider must decide how to interpret these handles. A service provider typically uses the pointer to its data structure or to the index into an array of data structures as its opaque handle. The only restriction is that the service provider cannot use the value 0 as an HDRVLINE, HDRVCALL, or HDRVPHONE. The value 0 or NULL for a handle has a special meaning in some operations.


Structure Extensibility

Provisions are made for extending constants and structures both in a device-independent way and in a device-specific (vendor-specific) way.

In constants that are scalar enumerations, a range of values is reserved for future common extensions. The remainder of values is identified as device specific. A vendor can define meanings for these values in any way. The interpretation of these values is keyed to the extension identifier provided through the LINEDEVCAPS data structure. For constants that are defined as bit flags, a range of low-order bits are reserved, where the high-order bits can be extension specific. It is recommended that extended values and bit arrays use bits from the highest value or high-order bit down. This leaves the option to move the border between the common portion and extension portion if there is need to do so in the future. Extensions to data structures are assigned a variably sized field with size/offset being part of the fixed part. TSPI describes for each data structure what device-specific extensions are allowed.

In addition to recognizing a specific extension identifier, TAPI (operating on behalf of an application) must negotiate the extension version number that the application and the service provider operate under. This is done using the TSPI_lineNegotiateExtVersion and TSPI_phoneNegotiateExtVersion functions.

An extension identifier is a globally unique identifier. There is no central registry for extension identifiers. Instead, they are generated locally by the manufacturer by a utility that is available with the toolkit. The number is made up of parts such as a (unique) LAN address, time of day, and random number, to guarantee global uniqueness. Globally unique identifiers are designed to be distinguishable from HP/DEC universally unique identifiers and are thus fully compatible with them.


TSPI Line Device Structures

This section describes the line device structures in the Telephony SPI.


LINEADDRESSCAPS

The LINEADDRESSCAPS structure describes the capabilities of a specified address.

typedef struct lineaddresscaps_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwLineDeviceID;

    DWORD  dwAddressSize;
    DWORD  dwAddressOffset;

    DWORD  dwDevSpecificSize;
    DWORD  dwDevSpecificOffset;

    DWORD  dwAddressSharing;
    DWORD  dwAddressStates;
    DWORD  dwCallInfoStates;
    DWORD  dwCallerIDFlags;
    DWORD  dwCalledIDFlags;
    DWORD  dwConnectedIDFlags;
    DWORD  dwRedirectionIDFlags;
    DWORD  dwRedirectingIDFlags;
    DWORD  dwCallStates;
    DWORD  dwDialToneModes;
    DWORD  dwBusyModes;
    DWORD  dwSpecialInfo;
    DWORD  dwDisconnectModes;

    DWORD  dwMaxNumActiveCalls;
    DWORD  dwMaxNumOnHoldCalls;
    DWORD  dwMaxNumOnHoldPendingCalls;
    DWORD  dwMaxNumConference;
    DWORD  dwMaxNumTransConf;

    DWORD  dwAddrCapFlags;
    DWORD  dwCallFeatures;
    DWORD  dwRemoveFromConfCaps;
    DWORD  dwRemoveFromConfState;
    DWORD  dwTransferModes;
    DWORD  dwParkModes;

    DWORD  dwForwardModes;
    DWORD  dwMaxForwardEntries;
    DWORD  dwMaxSpecificEntries;
    DWORD  dwMinFwdNumRings;
    DWORD  dwMaxFwdNumRings;

    DWORD  dwMaxCallCompletions;
    DWORD  dwCallCompletionConds;
    DWORD  dwCallCompletionModes;
    DWORD  dwNumCompletionMessages;
    DWORD  dwCompletionMsgTextEntrySize;
    DWORD  dwCompletionMsgTextSize;
    DWORD  dwCompletionMsgTextOffset;
} LINEADDRESSCAPS, FAR *LPLINEADDRESSCAPS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwLineDeviceID
The device identifier of the line device with which this address is associated.
dwAddressSize
dwAddressOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized address field.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device-specific field.
dwAddressSharing
The sharing mode of the address. This member uses the following LINEADDRESSSHARING_ constants:
LINEADDRESSSHARING_PRIVATE
An address with private sharing mode is only assigned to a single line or station.
LINEADDRESSSHARING_BRIDGEDEXCL
An address with a bridged-exclusive sharing mode is assigned to one or more other lines or stations. The exclusive portion refers to the fact that only one of the bridged parties can be connected with a remote party at any given time.
LINEADDRESSSHARING_BRIDGEDNEW
An address with a bridged-new sharing mode is assigned to one or more other lines or stations. The new portion refers to the fact that activities by the different bridged parties result in the creation of new calls on the address.
LINEADDRESSSHARING_BRIDGEDSHARED
An address with a bridged-shared sharing mode is also assigned to one or more other lines or stations. The shared portion refers to the fact that if one of the bridged parties is connected with a remote party, the remaining bridged parties can share in the conversation (as in a conference) by activating that call appearance.
LINEADDRESSSHARING_MONITORED
An address with a monitored address mode simply monitors the status of that address. The status is either idle or in use. The LINE_ADDRESSSTATE message notifies the application about these changes.
dwAddressStates
Contains the address state changes for which the application can be notified in the LINE_ADDRESSSTATE callback message. This member uses the following LINEADDRESSSTATE_ constants:
LINEADDRESSSTATE_OTHER
Address-status items other than those listed below have changed.
LINEADDRESSSTATE_DEVSPECIFIC
The device-specific item of the address status has changed.
LINEADDRESSSTATE_INUSEZERO
The address has changed to idle (it is now in use by zero stations).
LINEADDRESSSTATE_INUSEONE
The address has changed from being idle or from being in use by many bridged stations to being in use by just one station.
LINEADDRESSSTATE_INUSEMANY
The monitored or bridged address has changed from being in use by one station to being in use by more than one station.
LINEADDRESSSTATE_NUMCALLS
The number of calls on the address has changed. This is the result of events such as a new inbound call, an outbound call on the address, or a call changing its hold status.
LINEADDRESSSTATE_FORWARD
The forwarding status of the address has changed, including the number of rings for determining a no-answer condition. The application checks the address status to determine details about the address's current forwarding status.
LINEADDRESSSTATE_TERMINALS
The terminal settings for the address have changed.
dwCallInfoStates
Describes the call info elements that are meaningful for all calls on this address, and uses the LINECALLINFOSTATE_ constants. An application can get notified about changes in some of these states in LINE_CALLINFO messages. This member uses the following LINECALLINFOSTATE_ constants:
LINECALLINFOSTATE_OTHER
Call information items other than those listed below have changed.
LINECALLINFOSTATE_DEVSPECIFIC
The device-specific field of the call-information record.
LINECALLINFOSTATE_BEARERMODE
The bearer mode field of the call-information record.
LINECALLINFOSTATE_RATE
The rate field of the call-information record.
LINECALLINFOSTATE_MEDIAMODE
The media mode field of the call-information record.
LINECALLINFOSTATE_APPSPECIFIC
The application-specific field of the call-information record.
LINECALLINFOSTATE_CALLID
The call identifier field of the call-information record.
LINECALLINFOSTATE_RELATEDCALLID
The related call identifier field of the call-information record.
LINECALLINFOSTATE_ORIGIN
The origin field of the call-information record.
LINECALLINFOSTATE_REASON
The reason field of the call-information record.
LINECALLINFOSTATE_COMPLETIONID
The completion identifier field of the call-information record.
LINECALLINFOSTATE_NUMOWNERINCR
The number of owner field in the call-information record was increased.
LINECALLINFOSTATE_NUMOWNERDECR
The number of owner field in the call-information record was decreased.
LINECALLINFOSTATE_NUMMONITORS
The number of monitors field in the call-information record has changed.
LINECALLINFOSTATE_TRUNK
The trunk field of the call-information record.
LINECALLINFOSTATE_CALLERID
One of the callerID-related fields of the call-information record.
LINECALLINFOSTATE_CALLEDID
One of the calledID-related fields of the call-information record.
LINECALLINFOSTATE_CONNECTEDID
One of the connectedID-related fields of the call-information record.
LINECALLINFOSTATE_REDIRECTIONID
One of the redirectionID-related fields of the call-information record.
LINECALLINFOSTATE_REDIRECTINGID
One of the redirectingID-related fields of the call-information record.
LINECALLINFOSTATE_DISPLAY
The display field of the call-information record.
LINECALLINFOSTATE_USERUSERINFO
The user-user information of the call-information record.
LINECALLINFOSTATE_HIGHLEVELCOMP
The high-level compatibility field of the call-information record.
LINECALLINFOSTATE_LOWLEVELCOMP
The low-level compatibility field of the call-information record.
LINECALLINFOSTATE_CHARGINGINFO
The charging information of the call-information record.
LINECALLINFOSTATE_TERMINAL
The terminal mode information of the call-information record.
LINECALLINFOSTATE_DIALPARAMS
The dial parameters of the call-information record.
LINECALLINFOSTATE_MONITORMODES
One or more of the digit, tone, or media monitoring fields in the call-information record.
dwCallerIDFlags
dwCalledIDFlags
dwConnectedIDFlags
dwRedirectionIDFlags
dwRedirectingIDFlags
These fields describe the various kinds of party identifier information that can be provided for calls on this address. This member uses the following LINECALLPARTYID_ constants:
LINECALLPARTYID_BLOCKED
Caller identifier information for the call is blocked by the caller, but would otherwise be available.
LINECALLPARTYID_OUTOFAREA
Caller identifier information for the call is not available as it is not propagated all the way by the network.
LINECALLPARTYID_NAME
The caller identifier information for the call is the caller's name (from a table maintained inside the switch). It is provided in the caller identifier name variably sized field.
LINECALLPARTYID_ADDRESS
The caller identifier information for the call is the caller's number, and is provided in the caller identifier variably sized field.
LINECALLPARTYID_PARTIAL
Caller identifier information for the call is valid, but is limited to partial number information.
LINECALLPARTYID_UNKNOWN
Caller identifier information is currently unknown, but it can become known later.
LINECALLPARTYID_UNAVAIL
Caller identifier information is unavailable and cannot become known later.
dwCallStates
The various call states that can be reported for calls on this address. This member uses the following LINECALLSTATE_ constants:
LINECALLSTATE_IDLE
The call is idle; no call actually exists.
LINECALLSTATE_OFFERING
The call is being offered to the station, signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user; alerting is done by the switch instructing the line to ring. It does not affect any call states.
LINECALLSTATE_ACCEPTED
The call was offering and has been accepted. This indicates to other (monitoring) applications that the current owner application has claimed responsibility for answering the call. In ISDN, this also initiates alerting to both parties.
LINECALLSTATE_DIALTONE
The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number.
LINECALLSTATE_DIALING
Destination address information (a phone number) is being sent to the switch over the call. Note that the operation TSPI_lineGenerateDigits does not place the line into the dialing state.
LINECALLSTATE_RINGBACK
The call is receiving ringback from the called address. Ringback indicates that the other station has been reached and is being alerted.
LINECALLSTATE_BUSY
The call is receiving a busy tone. Busy tone indicates that the call cannot be completed because either a circuit (trunk) or the remote party's station is in use.
LINECALLSTATE_SPECIALINFO
Special information is sent by the network. Special information is typically sent when the destination cannot be reached.
LINECALLSTATE_CONNECTED
The call has been established, the connection is made. Information is able to flow over the call between the originating address and the destination address.
LINECALLSTATE_PROCEEDING
Dialing has completed and the call is proceeding through the switch or telephone network.
LINECALLSTATE_ONHOLD
The call is on hold by the switch.
LINECALLSTATE_CONFERENCED
The call is currently a member of a multiparty conference call.
LINECALLSTATE_ONHOLDPENDCONF
The call is currently on hold while it is being added to a conference.
LINECALLSTATE_ONHOLDPENDTRANSFER
The call is currently on hold awaiting transfer to another number.
LINECALLSTATE_DISCONNECTED
The remote party has disconnected from the call.
LINECALLSTATE_UNKNOWN
The state of the call is not known. This can be due to limitations of the call progress detection implementation.
dwDialToneModes
The various dial tone modes that can possibly be reported for calls made on this address. This member uses the following LINEDIALTONEMODE_ constants. This member is only meaningful if the dialtone call state can be reported.
LINEDIALTONEMODE_NORMAL
This is a normal dial tone that typically is a continuous tone.
LINEDIALTONEMODE_SPECIAL
This is a special dial tone indicating a certain condition is currently in effect.
LINEDIALTONEMODE_INTERNAL
This an internal dial tone, as within a PBX.
LINEDIALTONEMODE_EXTERNAL
This is an external (public network) dial tone.
LINEDIALTONEMODE_UNKNOWN
The dial tone mode is currently unknown, but can become known later.
LINEDIALTONEMODE_UNAVAIL
The dial tone mode is unavailable and cannot become known.
dwBusyModes
The various busy modes that can possibly be reported for calls made on this address. This member uses the following LINEBUSYMODE_ constants. This member is only meaningful if the busy call state can be reported.
LINEBUSYMODE_STATION
The busy signal indicates that the called party's station is busy. This is usually signaled by means of a normal busy tone.
LINEBUSYMODE_TRUNK
The busy signal indicates that a trunk or circuit is busy. This is usually signaled by means of a long busy tone.
LINEBUSYMODE_UNKNOWN
The busy signal's specific mode is currently unknown, but can become known later.
LINEBUSYMODE_UNAVAIL
The busy signal's specific mode is unavailable and cannot become known.
dwSpecialInfo
The various kinds of special information that can be reported for calls made on this address. It uses the following LINESPECIALINFO_ constants. This member is only meaningful if the specialInfo call state can be reported.
LINESPECIALINFO_NOCIRCUIT
This special information tone precedes a no-circuit or emergency announcement (trunk blockage category).
LINESPECIALINFO_CUSTIRREG
This special information tone precedes a vacant number, AIS, Centrex number change and nonworking station, access code not dialed or dialed in error, or manual intercept operator message (customer irregularity category).
LINESPECIALINFO_REORDER
This special information tone precedes a reorder announcement (equipment irregularity category).
LINESPECIALINFO_UNKNOWN
Specifics about the special information tone are currently unknown but can become known later.
LINESPECIALINFO_UNAVAIL
Specifics about the special information tone are unavailable, and cannot become known.
dwDisconnectModes
The various disconnect modes that can possibly be reported for calls made on this address. This member uses the LINEDISCONNECTMODE_ constants listed below. This member is only meaningful if the disconnected call state can be reported.
LINEDISCONNECTMODE_NORMAL
A normal disconnect request by the remote party; the call is terminated normally.
LINEDISCONNECTMODE_UNKNOWN
The reason for the disconnect request is unknown.
LINEDISCONNECTMODE_REJECT
The remote user has rejected the call.
LINEDISCONNECTMODE_PICKUP
The call was picked up from elsewhere.
LINEDISCONNECTMODE_FORWARDED
The call was forwarded by the switch.
LINEDISCONNECTMODE_BUSY
The remote user's station is busy.
LINEDISCONNECTMODE_NOANSWER
The remote user's station does not answer.
LINEDISCONNECTMODE_BADADDRESS
The destination address in invalid.
LINEDISCONNECTMODE_CONGESTION
The network is congested.
LINEDISCONNECTMODE_INCOMPATIBLE
The remote user's station equipment is incompatible for the type of call requested.
LINEDISCONNECTMODE_UNAVAIL
The reason for the disconnect is unavailable and cannot become known later.
LINEDISCONNECTMODE_NODIALTONE
A dial tone was not detected within a service-provider defined timeout, at a point during dialing when one was expected (such as at a "W" in the dialable string). This can also occur without a service-provider defined timeout period or without a value specified in the dwWaitForDialTone member of the LINEDIALPARAMS structure.
dwMaxNumActiveCalls
The maximum number of active call appearances that the address can handle. This number does not include calls on hold or on hold pending transfer or conference.
dwMaxNumOnHoldCalls
The maximum number of call appearances at the address that can be on hold.
dwMaxNumOnHoldPendingCalls
The maximum number of call appearances at the address that can be on hold pending transfer or conference.
dwMaxNumConference
The maximum number of parties that can be conferenced in a single conference call on this address.
dwMaxNumTransConf
The number of parties (including "self") that can be added in a conference call that is initiated as a generic consultation call using the lineSetupTransfer function.
dwAddrCapFlags
A series of packed bit flags that describe a variety of address capabilities. This member uses the following LINEADDRCAPFLAGS_ constants:
LINEADDRCAPFLAGS_FWDNUMRINGS
Specify whether the number of rings for a no answer can be specified when forwarding calls on no answer.
LINEADDRCAPFLAGS_PICKUPGROUPID
Specify whether a group identifier is required for call pickup.
LINEADDRCAPFLAGS_SECURE
Specify whether calls on this address can be made secure at call setup time.
LINEADDRCAPFLAGS_BLOCKIDDEFAULT
Specify whether the network by default sends or blocks caller ID information when making a call on this address. If TRUE, identifier information is blocked by default; if FALSE, identifier information is transmitted by default.
LINEADDRCAPFLAGS_BLOCKIDOVERRIDE
Specify whether the default setting for sending or blocking of caller ID information can be overridden per call. If TRUE, override is possible; if FALSE, override is not possible.
LINEADDRCAPFLAGS_DIALED
Specify whether a destination address can be dialed on this address for making a call. TRUE if a destination address must be dialed; FALSE if the destination address is fixed (as with a "hot phone").
LINEADDRCAPFLAGS_ORIGOFFHOOK
Specify whether the originating party's phone can automatically be taken offhook when making calls.
LINEADDRCAPFLAGS_DESTOFFHOOK
Specify whether the called party's phone can automatically be forced offhook when making calls.
LINEADDRCAPFLAGS_FWDCONSULT
Specify whether call forwarding involves the establishment of a consultation call.
LINEADDRCAPFLAGS_SETUPCONFNULL
Specify whether setting up a conference call starts out with an initial call (FALSE) or with no initial call (TRUE).
LINEADDRCAPFLAGS_AUTORECONNECT
Specify whether dropping a consultation call automatically reconnects to the call on consultation hold. TRUE if reconnect happens automatically, otherwise FALSE.
LINEADDRCAPFLAGS_COMPLETIONID
Specify whether the completion identifiers returned by TSPI_lineCompleteCall are useful and unique. TRUE if useful; otherwise, FALSE.
LINEADDRCAPFLAGS_TRANSFERHELD
Specify whether a (hard) held call can be transferred. Often, only calls on consultation hold can be transferred.
LINEADDRCAPFLAGS_TRANSFERMAKE
Specify whether an entirely new call can be established for use as a consultation call on transfer.
LINEADDRCAPFLAGS_CONFERENCEHELD
Specify whether a (hard) held call can be conferenced to. Often, only calls on consultation hold can be added to as a conference call.
LINEADDRCAPFLAGS_CONFERENCEMAKE
Specify whether an entirely new call can be established for use as a consultation call (to add) on conference.
LINEADDRCAPFLAGS_PARTIALDIAL
Specify whether partial dialing is available.
LINEADDRCAPFLAGS_FWDSTATUSVALID
Specify whether the forwarding status in the LINEADDRESSSTATUS structure for this address is valid.
LINEADDRCAPFLAGS_FWDINTEXTADDR
Specify whether internal and external calls can be forwarded to different forwarding addresses. This flag is only meaningful if forwarding of internal and external calls can be controlled separately. This flag is TRUE if internal and external calls can be forwarded to different destination addresses; otherwise, FALSE.
LINEADDRCAPFLAGS_FWDBUSYNAADDR
Specify whether call forwarding for busy and no answer can use different forwarding addresses. This flag is only meaningful if forwarding for busy and no answer can be controlled separately. This flag is TRUE if forwarding for busy and no answer can be use different destination addresses; othewise, FALSE.
LINEADDRCAPFLAGS_ACCEPTTOALERT
This flag is TRUE if an offering call must be accepted using lineAccept to start alerting the users at both ends of the call; Otherwise, it is FALSE. This flag is typically only used with ISDN.
LINEADDRCAPFLAGS_CONFDROP
This flag is TRUE if lineDrop of a conference call parent also has the side effect of dropping (disconnecting) the other parties involved in the conference call. It is FALSE if dropping a conference call still allows the other parties to talk among themselves.
LINEADDRCAPFLAGS_PICKUPCALLWAIT
This flag is TRUE if linePickup can be used to pick up a call detected by the user as a call-waiting call. Otherwise, it is FALSE.
dwCallFeatures
The switching capabilities or features available for all calls on this address, of type LINECALLFEATURE. Invoking a supported feature requires the call to be in the proper state and the underlying line device to be opened in a compatible mode. A zero in a bit position indicates that the corresponding feature is never available; a one indicates that the corresponding feature may be available if the application has the right privileges to the call, and the call is in the appropriate state for the operation to be meaningful. This member allows an aplication to discover early on which call features can be and which can never be supported by the address.
dwRemoveFromConfCaps
The address's capabilities for removing calls from a conference call. This member uses the following LINEREMOVEFROMCONF_ constants:
LINEREMOVEFROMCONF_NONE
Parties cannot be removed from the conference call.
LINEREMOVEFROMCONF_LAST
Only the most recently added party can be removed from the conference call.
LINEREMOVEFROMCONF_ANY
Any participating party can be removed from the conference call.
dwRemoveFromConfState
This member is of the type LINECALLSTATE, and specifies the state of the call after it is removed from a conference call.
dwTransferModes
The address's capabilities for resolving transfer requests. This member uses the following LINETRANSFERMODE_ constants:
LINETRANSFERMODE_TRANSFER
Resolve the initiated transfer by transferring the initial call to the consultation call.
LINETRANSFERMODE_CONFERENCE
Resolve the initiated transfer by conferencing all three parties into a three-way conference call. A conference call is created and returned to the application.
dwParkModes
Specifies the different call park modes available at this address, and uses the following LINEPARKMODE_ constants:
LINEPARKMODE_DIRECTED
Specify directed call park. The address where the call is to be parked must be supplied to the switch.
LINEPARKMODE_NONDIRECTED
Specify nondirected call park. The address where the call is parked is selected by the switch and provided by the switch to the application.
dwForwardModes
The different modes of forwarding available for this address. This member uses the following LINEFORWARDMODE_ constants:
LINEFORWARDMODE_UNCOND
Forward all calls unconditionally, irrespective of their origin. Use this value when unconditional forwarding for internal and external calls cannot be controlled separately. Unconditional forwarding overrides forwarding on busy and/or no-answer conditions.
LINEFORWARDMODE_UNCONDINTERNAL
Forward all internal calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.
LINEFORWARDMODE_UNCONDEXTERNAL
Forward all external calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.
LINEFORWARDMODE_UNCONDSPECIFIC
Forward all calls that originated at a specified address unconditionally (selective call forwarding).
LINEFORWARDMODE_BUSY
Forward all calls on busy, irrespective of their origin. Use this value when forwarding for internal and external calls on busy and no answer cannot be controlled separately.
LINEFORWARDMODE_BUSYINTERNAL
Forward all internal calls on busy. Use this value when forwarding for internal and external calls on busy and no answer can be controlled separately.
LINEFORWARDMODE_BUSYEXTERNAL
Forward all external calls on busy. Use this value when forwarding for internal and external calls on busy and no answer can be controlled separately.
LINEFORWARDMODE_BUSYSPECIFIC
Forward all calls that originated at a specified address on busy (selective call forwarding).
LINEFORWARDMODE_NOANSW
Forward all calls on no answer, irrespective of their origin. Use this value when call forwarding for internal and external calls on no answer cannot be controlled separately.
LINEFORWARDMODE_NOANSWINTERNAL
Forward all internal calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.
LINEFORWARDMODE_NOANSWEXTERNAL
Forward all external calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.
LINEFORWARDMODE_NOANSWSPECIFIC
Forward all calls that originated at a specified address on no answer (selective call forwarding).
LINEFORWARDMODE_BUSYNA
Forward all calls on busy/no answer irrespective of their origin. Use this value when forwarding for internal and external calls on busy and no answer cannot be controlled separately.
LINEFORWARDMODE_BUSYNAINTERNAL
Forward all internal calls on busy/no answer. Use this value when call forwarding on busy and no answer cannot be controlled separately for internal calls.
LINEFORWARDMODE_BUSYNAEXTERNAL
Forward all external calls on busy/no answer. Use this value when call forwarding on busy and no answer cannot be controlled separately for internal calls.
LINEFORWARDMODE_BUSYNASPECIFIC
Forward all calls that originated at a specified address on busy/no answer (selective call forwarding).
dwMaxForwardEntries
The maximum number of entries that can be passed to TSPI_lineForward in the lpForwardList parameter.
dwMaxSpecificEntries
The maximum number of entries in the lpForwardList parameter passed to TSPI_lineForward that can contain forwarding instructions based on a specific caller ID (selective call forwarding). This member is zero if selective call forwarding is not supported.
dwMinFwdNumRings
The minimum number of rings that can be set to determine when a call is officially considered "no answer."
dwMaxFwdNumRings
The maximum number of rings that can be set to determine when a call is officially considered "no answer." If this number of rings cannot be set, then dwMinFwdNumRings and dwMaxNumRings are equal.
dwMaxCallCompletions
The maximum number of concurrent call completion requests that can be outstanding on this line device. Zero implies that call completion is not available.
dwCallCompletionCond
The different call conditions under which call completion can be requested. This member uses the following LINECALLCOMPLCOND_ constants:
LINECALLCOMPLCOND_BUSY
Complete the call under the busy condition.
LINECALLCOMPLCOND_NOANSWER
Complete the call under the ringback, no-answer condition.
dwCallCompletionModes
The way in which the call can be completed. This member uses the following LINECALLCOMPLMODE_ constants:
LINECALLCOMPLMODE_CAMPON
Queue the call until the call can be completed.
LINECALLCOMPLMODE_CALLBACK
Request the called station to return the call when it returns to idle.
LINECALLCOMPLMODE_INTRUDE
Add the application to the existing call at the called station if busy (barge in).
LINECALLCOMPLMODE_MESSAGE
Leave a short, predefined message for the called station (Leave Word Calling). A specific message can be identified.
dwNumCompletionMessages
The number of call completion messages from which a selection can be made when using the LINECALLCOMPLMODE_MESSAGE option. Individual messages are identified by values in the range 0 through dwNumCompletionMessages minus one.
dwCompletionMsgTextEntrySize
The size in bytes of each of the call completion text descriptions pointed at by dwCompletionMsgTextSize/Offset.
dwCompletionMsgTextSize
dwCompletionMsgTextOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field containing descriptive text about each of the call completion messages. Each message is dwCompletionMsgTextEntrySize bytes long. The string format of these textual descriptions is indicated by dwStringFormat in the line's device capabilities.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

See Also

LINEADDRESSMODE_ Constants, LINEADDRESSSTATUS, LINEBEARERMODE_ Constants, LINECALLCOMPLCOND_ Constants, LINECALLCOMPLMODE_ Constants, LINECALLFEATURE_ Constants, LINECALLORIGIN_ Constants, LINEDIALPARAMS, LINEFORWARDMODE_ Constants, LINEMEDIAMODE_ Constants, LINEPARKMODE_ Constants, TSPI_lineCompleteCall, TSPI_lineForward, TSPI_lineGenerateDigits, TSPI_lineGetAddressCaps


LINEADDRESSSTATUS

The LINEADDRESSSTATUS structure describes the current status of an address.

typedef struct lineaddressstatus_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;

  DWORD  dwNumInUse;
  DWORD  dwNumActiveCalls;
  DWORD  dwNumOnHoldCalls;
  DWORD  dwNumOnHoldPendCalls;
  DWORD  dwAddressFeatures;

  DWORD  dwNumRingsNoAnswer;
  DWORD  dwForwardNumEntries;
  DWORD  dwForwardSize;
  DWORD  dwForwardOffset;

  DWORD  dwTerminalModesSize;
  DWORD  dwTerminalModesOffset;

  DWORD  dwDevSpecificSize;
  DWORD  dwDevSpecificOffset;
} LINEADDRESSSTATUS, FAR *LPLINEADDRESSSTATUS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwNumInUse
The number of stations that are currently using the address.
dwNumActiveCalls
The number of calls on the address that are in call states other than idle, onHold, onHoldPendingTransfer, and onHoldPendingConference.
dwNumOnHoldCalls
The number of calls on the address in the onHold state.
dwNumOnHoldPendCalls
The number of calls on the address in the onHoldPendingTransfer or onHoldPendingConference state.
dwAddressFeatures
The address-related API functions that can be invoked on the address in its current state. This member uses the following LINEADDRFEATURE_ constants:
LINEADDRFEATURE_FORWARD
The address can be forwarded.
LINEADDRFEATURE_MAKECALL
An outbound call can be placed on the address.
LINEADDRFEATURE_PICKUP
A call can be picked up at the address.
LINEADDRFEATURE_SETMEDIACONTROL
Media control can be set on this address.
LINEADDRFEATURE_SETTERMINAL
The terminal modes for this address can be set.
LINEADDRFEATURE_SETUPCONF
A conference call with a NULL initial call can be set up at this address.
LINEADDRFEATURE_UNCOMPLETECALL
Call completion requests can be canceled at this address.
LINEADDRFEATURE_UNPARK
Calls can be unparked using this address.
dwNumRingsNoAnswer
The number of rings set for this address before an unanswered call is considered as no answer.
dwForwardNumEntries
The number of entries in the array referred to by dwForwardSize and dwForwardOffset.
dwForwardSize
dwForwardOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field that describes the address's forwarding information. This information is an array of dwForwardNumEntries elements, of type LINEFORWARD. The offsets of the addresses in the array are relative to the beginning of the LINEADDRESSTATUS structure.
dwTerminalModesSize
dwTerminalModesOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device field containing an array with DWORD-sized entries, of type LINETERMMODE. This array is indexed by terminal identifiers, in the range from zero to dwNumTerminals minus one. Each entry in the array specifies the current terminal modes for the corresponding terminal set through the TSPI_lineSetTerminal operation for this address. Values are:
LINETERMMODE_BUTTONS
Button press events sent from the terminal to the line.
LINETERMMODE_LAMPS
Lamp events sent from the line to the terminal.
LINETERMMODE_DISPLAY
Display information sent from the line to the terminal.
LINETERMMODE_RINGER
Ringer control information sent from the switch to the terminal.
LINETERMMODE_HOOKSWITCH
Hookswitch event sent between the terminal and the line.
LINETERMMODE_MEDIATOLINE
The unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIAFROMLINE
The unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIABIDIRECT
The bidirectional media stream associated with a call on the line and the terminal. Use this value when routing of both unidirectional channels of a call's media stream cannot be controlled independently.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device-specific field.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

This data structure is returned by TSPI_lineGetAddressStatus. When items in this data structure change as a consequence of activities on the address, a LINE_ADDRESSSTATE message is sent to the application. A parameter to this message is the address state, of type LINEADDRESSSTATE_, which is an indication of the status item in this record that changed.

See Also

LINE_ADDRESSSTATE, LINEADDRFEATURE_ Constants, LINEFORWARD, LINETERMMODE_ Constants, TSPI_lineGetAddressStatus, TSPI_lineSetTerminal


LINECALLINFO

The LINECALLINFO structure contains information about a call. This information remains relatively fixed for the duration of the call and is obtained using TSPI_lineGetCallInfo. If a part of the structure does change, a LINE_CALLINFO message is sent to the application indicating which information item has changed. Dynamically changing information about a call, such as call progress status, is available in the LINECALLSTATUS structure, returned with the function TSPI_lineGetCallStatus.

typedef struct linecallinfo_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    HLINE  hLine;
    DWORD  dwLineDeviceID;
    DWORD  dwAddressID;

    DWORD  dwBearerMode;
    DWORD  dwRate;
    DWORD  dwMediaMode;

    DWORD  dwAppSpecific;
    DWORD  dwCallID;
    DWORD  dwRelatedCallID;
    DWORD  dwCallParamFlags;
    DWORD  dwCallStates;

    DWORD  dwMonitorDigitModes;
    DWORD  dwMonitorMediaModes;
    LINEDIALPARAMS  DialParams;

    DWORD  dwOrigin;
    DWORD  dwReason;
    DWORD  dwCompletionID;
    DWORD  dwNumOwners;
    DWORD  dwNumMonitors;

    DWORD  dwCountryCode;
    DWORD  dwTrunk;

    DWORD  dwCallerIDFlags;
    DWORD  dwCallerIDSize;
    DWORD  dwCallerIDOffset;
    DWORD  dwCallerIDNameSize;
    DWORD  dwCallerIDNameOffset;

    DWORD  dwCalledIDFlags;
    DWORD  dwCalledIDSize;
    DWORD  dwCalledIDOffset;
    DWORD  dwCalledIDNameSize;
    DWORD  dwCalledIDNameOffset;

    DWORD  dwConnectedIDFlags;
    DWORD  dwConnectedIDSize;
    DWORD  dwConnectedIDOffset;
    DWORD  dwConnectedIDNameSize;
    DWORD  dwConnectedIDNameOffset;

    DWORD  dwRedirectionIDFlags;
    DWORD  dwRedirectionIDSize;
    DWORD  dwRedirectionIDOffset;
    DWORD  dwRedirectionIDNameSize;
    DWORD  dwRedirectionIDNameOffset;

    DWORD  dwRedirectingIDFlags;
    DWORD  dwRedirectingIDSize;
    DWORD  dwRedirectingIDOffset;
    DWORD  dwRedirectingIDNameSize;
    DWORD  dwRedirectingIDNameOffset;

    DWORD  dwAppNameSize;
    DWORD  dwAppNameOffset;

    DWORD  dwDisplayableAddressSize
    DWORD  dwDisplayableAddressOffset

    DWORD  dwCalledPartySize;
    DWORD  dwCalledPartyOffset;

    DWORD  dwCommentSize;
    DWORD  dwCommentOffset;

    DWORD  dwDisplaySize;
    DWORD  dwDisplayOffset;

    DWORD  dwUserUserInfoSize;
    DWORD  dwUserUserInfoOffset;

    DWORD  dwHighLevelCompSize;
    DWORD  dwHighLevelCompOffset;

    DWORD  dwLowLevelCompSize;
    DWORD  dwLowLevelCompOffset;

    DWORD  dwChargingInfoSize;
    DWORD  dwChargingInfoOffset;

    DWORD  dwTerminalModesSize;
    DWORD  dwTerminalModesOffset;

    DWORD  dwDevSpecificSize;
    DWORD  dwDevSpecificOffset;
} LINECALLINFO, FAR *LPLINECALLINFO;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
hLine
Handle for the line device with which this call is associated.
dwLineDeviceID
The device identifier of the line device with which this call is associated.
dwAddressID
The address identifier of the address on the line on which this call exists.
dwBearerMode
The current bearer mode of the call. This member uses the following LINEBEARERMODE_ constants:
LINEBEARERMODE_VOICE
Regular 3.1kHz analog voice grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.
LINEBEARERMODE_SPEECH
Corresponds to G.711 speech transmission on the call. The network can use processing techniques such as analog transmission, echo cancellation and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.
LINEBEARERMODE_MULTIUSE
The multiuse mode defined by ISDN.
LINEBEARERMODE_DATA
The unrestricted data transfer on the call. The data rate is specified separately.
LINEBEARERMODE_ALTSPEECHDATA
The alternate transfer of speech or unrestricted data on the same call (ISDN).
LINEBEARERMODE_NONCALLSIGNALING
Corresponds to a non-call-associated signaling connection from the application to the service provider or switch (treated as a media stream by the Telephony API).
LINEBEARERMODE_PASSTHROUGH
When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 comm functions, for the purpose of configuring or using special features not otherwise supported by the service provider.
dwRate
The rate of the call's data stream in bps (bits per second).
dwMediaMode
The media mode of the information stream currently on the call, of type LINEMEDIAMODE_. This is the media mode as determined by the owner of the call, which is not necessarily the same as that of the last LINE_MONITORMEDIA message. This member is not directly affected by LINE_MONITORMEDIA messages. Values are:
LINEMEDIAMODE_UNKNOWN
A media stream exists but its mode is not known. This corresponds to a call with an unclassified media type. In typical analog telephony environments, an inbound call's media mode may be unknown until after the call is answered and the media stream is filtered to make a determination.
LINEMEDIAMODE_INTERACTIVEVOICE
The presence of voice energy on the call and the call is treated as an interactive call with humans on both ends.
LINEMEDIAMODE_AUTOMATEDVOICE
The presence of voice energy on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM
A data modem session on the call.
LINEMEDIAMODE_G3FAX
A group 3 fax is being sent or received over the call.
LINEMEDIAMODE_TDD
A TDD (Telephony Devices for the Deaf) session on the call.
LINEMEDIAMODE_G4FAX
A group 4 fax is being sent or received over the call.
LINEMEDIAMODE_DIGITALDATA
Digital data is being sent or received over the call.
LINEMEDIAMODE_TELETEX
A teletex session on the call. Teletex is one of the telematic services.
LINEMEDIAMODE_VIDEOTEX
A videotex session on the call. Videotex is one the telematic services.
LINEMEDIAMODE_TELEX
A telex session on the call. Telex is one the telematic services.
LINEMEDIAMODE_MIXED
A mixed session on the call. Mixed is one of the ISDN telematic services.
LINEMEDIAMODE_ADSI
An ADSI (Analog Display Services Interface) session on the call.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.
dwAppSpecific
This member is uninterpreted by the API implementation and service provider. It can be set by any owner application of this call with TSPI_lineSetAppSpecific.
dwCallID
In some telephony environments, the switch or service provider can assign a unique identifier to each call. This allows the call to be tracked across transfers, forwards, or other events. The domain of these call identifiers and their scope is service-provider defined. The dwCallID member makes this unique identifier available to the applications.
dwRelatedCallID
Telephony environments that use the call ID often may find it necessary to relate one call to another. The dwRelatedCallID member can be used by the service provider for this purpose.
dwCallParamFlags
A collection of call-related parameters when the call is outbound. These are the same call parameters specified through TSPI_lineMakeCall, of type LINECALLPARAMFLAGS_. Values are:
LINECALLPARAMFLAGS_SECURE
The call is currently secure. This flag is also updated if the call is later secured with TSPI_lineSecureCall.
LINECALLPARAMFLAGS_IDLE
The call started out using an idle call.
LINECALLPARAMFLAGS_BLOCKID
The originator identity is concealed (blocked caller ID presentation to the remote party).
LINECALLPARAMFLAGS_ORIGOFFHOOK
The originator's phone is automatically taken offhook.
LINECALLPARAMFLAGS_DESTOFFHOOK
The called party's phone is automatically taken offhook.
dwCallStates
The call states for which the application can be notified on this call. This member uses the LINECALLSTATE_ constants listed below. The dwCallStates member is constant in LINECALLINFO. It describes the call states that can be reported during the lifetime of this call, and does not change depending on call state. (LINECALLINFO should be seen as a "call caps".) Values are:
LINECALLSTATE_IDLE
The call is idle; no call actually exists.
LINECALLSTATE_OFFERING
The call is being offered to the station, signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user; alerting is done by the switch instructing the line to ring. It does not affect any call states.
LINECALLSTATE_ACCEPTED
The call was offering and is accepted. This indicates to other (monitoring) applications that the current owner application has claimed responsibility for answering the call. In ISDN, this also initiates alerting to both parties.
LINECALLSTATE_DIALTONE
The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number.
LINECALLSTATE_DIALING
Destination address information (a phone number) is being sent to the switch over the call. Note that the operation TSPI_lineGenerateDigits does not place the line into the dialing state.
LINECALLSTATE_RINGBACK
The call is receiving ringback from the called address. Ringback indicates that the other station has been reached and is being alerted.
LINECALLSTATE_BUSY
The call is receiving a busy tone. Busy tone indicates that the call cannot be completed because either a circuit (trunk) or the remote party's station are in use.
LINECALLSTATE_SPECIALINFO
Special information is sent by the network. Special information is typically sent when the destination cannot be reached.
LINECALLSTATE_CONNECTED
The call is established, the connection is made. Information is able to flow over the call between the originating address and the destination address.
LINECALLSTATE_PROCEEDING
Dialing is completed and the call is proceeding through the switch or telephone network.
LINECALLSTATE_ONHOLD
The call is on hold by the switch.
LINECALLSTATE_CONFERENCED
The call is currently a member of a multiparty conference call.
LINECALLSTATE_ONHOLDPENDCONF
The call is currently on hold while it is being added to a conference.
LINECALLSTATE_ONHOLDPENDTRANSFER
The call is currently on hold awaiting transfer to another number.
LINECALLSTATE_DISCONNECTED
The remote party has disconnected from the call.
LINECALLSTATE_UNKNOWN
The state of the call is not known. This can be due to limitations of the call progress detection implementation.
dwMonitorDigitModes
The various digit modes for which monitoring is currently enabled. This member uses the following LINEDIGITMODE_ constants:
LINEDIGITMODE_PULSE
Use pulse/rotary for digit signaling.
LINEDIGITMODE_DTMF
Use DTMF tones for digit signaling.
LINEDIGITMODE_DTMFEND
Use DTMF tones for digit detection, and also detect the down edges.
dwMonitorMediaModes
The various media modes for which monitoring is currently enabled. This member uses the following LINEMEDIAMODE_ constants:
LINEMEDIAMODE_INTERACTIVEVOICE
The presence of voice energy on the call and the call is treated as an interactive call with humans on both ends.
LINEMEDIAMODE_AUTOMATEDVOICE
The presence of voice energy on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM
A data modem session on the call.
LINEMEDIAMODE_G3FAX
A group 3 fax is being sent or received over the call.
LINEMEDIAMODE_TDD
A TDD (Telephony Devices for the Deaf) session on the call.
LINEMEDIAMODE_G4FAX
A group 4 fax is being sent or received over the call.
LINEMEDIAMODE_DIGITALDATA
Digital data is being sent or received over the call.
LINEMEDIAMODE_TELETEX
A teletex session on the call. Teletex is one of the telematic services.
LINEMEDIAMODE_VIDEOTEX
A videotex session on the call. Videotex is one the telematic services.
LINEMEDIAMODE_TELEX
A telex session on the call. Telex is one the telematic services.
LINEMEDIAMODE_MIXED
A mixed session on the call. Mixed is one the ISDN telematic services.
LINEMEDIAMODE_ADSI
An ADSI (Analog Display Services Interface) session on the call.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.
DialParams
The dialing parameters currently in effect on the call, of type LINEDIALPARAMS. Unless these parameters are set by either TSPI_lineMakeCall or TSPI_lineSetCallParams, their values are the same as the defaults used in LINEDEVCAPS.
dwOrigin
Identifies where the call originated from. This member uses the following LINECALLORIGIN_ constants:
LINECALLORIGIN_OUTBOUND
The call is an outbound call.
LINECALLORIGIN_INTERNAL
The call is inbound and originated internally (on the same PBX, for example).
LINECALLORIGIN_EXTERNAL
The call is inbound and originated externally.
LINECALLORIGIN_UNKNOWN
The call is an inbound call, but its origin is currently unknown but can become known later.
LINECALLORIGIN_UNAVAIL
The call is an inbound call, and its origin is not available and cannot become known for this call.
LINECALLORIGIN_CONFERENCE
The call handle is for a conference call, that is, the application's connection to the conference bridge in the switch.
dwReason
The reason why the call occurred. This member uses the following LINECALLREASON_ constants:
LINECALLREASON_DIRECT
This is a direct call.
LINECALLREASON_FWDBUSY
This call was forwarded from another extension that was busy at the time of the call.
LINECALLREASON_FWDNOANSWER
The call was forwarded from another extension that didn't answer the call after some number of rings.
LINECALLREASON_FWDUNCOND
The call was forwarded unconditionally from another number.
LINECALLREASON_PICKUP
The call was picked up from another extension.
LINECALLREASON_UNPARK
The call was retrieved as a parked call.
LINECALLREASON_REDIRECT
The call was redirected to this station.
LINECALLREASON_CALLCOMPLETION
The call was the result of a call completion request.
LINECALLREASON_TRANSFER
The call has been transferred from another number. Party identifier information can indicate who the caller is and where the call was transferred from.
LINECALLREASON_REMINDER
The call is a reminder (or recall) that the user has a call parked or on hold for potentially a long time.
LINECALLREASON_UNKNOWN
The reason for the call is currently unknown but can become known later.
LINECALLREASON_UNAVAIL
The reason for the call is unavailable and cannot become known later.
dwCompletionID
The completion identifier for the incoming call if it is the result of a completion request that terminates. This identifier is meaningful only if dwReason is LINECALLREASON_CALLCOMPLETION.
dwNumOwners
The number of application modules with different call handles with owner privilege for the call.
dwNumMonitors
The number of application modules with different call handles with monitor privilege for the call.
dwCountryCode
The country code of the destination party. Zero if unknown.
dwTrunk
The number of the trunk over which the call is routed. This member is used for both inbound and outgoing calls, and should be set to 0xFFFFFFFF if it is unknown.
dwCallerIDFlags
Determines the validity and content of the caller party identifier information. The caller is the originator of the call. This member uses the following LINECALLPARTYID_ constants:
LINECALLPARTYID_BLOCKED
Caller ID information for the call is blocked by the caller, but would otherwise be available.
LINECALLPARTYID_OUTOFAREA
Caller ID information for the call is not available because it is not propagated all the way by the network.
LINECALLPARTYID_NAME
The caller ID information for the call is the caller's name (from a table maintained inside the switch). It is provided in the caller ID name variably sized field.
LINECALLPARTYID_ADDRESS
The caller ID information for the call is the caller's number, and is provided in the caller ID variably sized field.
LINECALLPARTYID_PARTIAL
Caller ID information for the call is valid, but is limited to partial number information.
LINECALLPARTYID_UNKNOWN
Caller ID information is currently unknown, but it can become known later.
LINECALLPARTYID_UNAVAIL
Caller ID information is unavailable and cannot become known later.
dwCallerIDSize
dwCallerIDOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing the caller party ID number information.
dwCallerIDNameSize
dwCallerIDNameOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing the caller party ID name information.
dwCalledIDFlags
Determines the validity and content of the called party ID information. The called party corresponds to the orignally addressed party. This member uses the following LINECALLPARTYID_ constants:
LINECALLPARTYID_BLOCKED
Called ID information for the call is blocked by the caller, but would otherwise be available.
LINECALLPARTYID_OUTOFAREA
Caller ID information for the call is not available as it is not propagated all the way by the network.
LINECALLPARTYID_NAME
The called ID information for the call is the caller's name (from a table maintained inside the switch). It is provided in the called ID name variably sized field.
LINECALLPARTYID_ADDRESS
The called ID information for the call is the caller's number, and is provided in the called ID variably sized field.
LINECALLPARTYID_PARTIAL
Called ID information for the call is valid, but is limited to partial number information.
LINECALLPARTYID_UNKNOWN
Called ID information is currently unknown but it can become known later.
LINECALLPARTYID_UNAVAIL
Called ID information is unavailable and cannot become known later.
dwCalledIDSize
dwCalledIDOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing the called party ID number information.
dwCalledIDNameSize
dwCalledIDNameOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing the called party ID name information.
dwConnectedFlags
Determines the validity and content of the connected party ID information. The connected party is the party that was actually connected to. This can be different from the called party ID if the call was diverted. This member uses the following LINECALLPARTYID_ constants:
LINECALLPARTYID_BLOCKED
Connected party identifier information for the call is blocked by the caller, but would otherwise be available.
LINECALLPARTYID_OUTOFAREA
Connected identifier information for the call is not available as it is not propagated all the way by the network.
LINECALLPARTYID_NAME
The connected party identifier information for the call is the caller's name (from a table maintained inside the switch). It is provided in the connected identifier name variably sized field.
LINECALLPARTYID_ADDRESS
The connected party identifier information for the call is the caller's number, and is provided in the connected identifier variably sized field.
LINECALLPARTYID_PARTIAL
Connected party identifier information for the call is valid, but is limited to partial number information.
LINECALLPARTYID_UNKNOWN
Connected party identifier information is currently unknown, but can become known later.
LINECALLPARTYID_UNAVAIL
Connected party identifier information is unavailable and cannot become known later.
dwConnectedIDSize
dwConnectedIDOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing the connected party identifier number information.
dwConnectedIDNameSize
dwConnectedIDNameOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing the connected party identifier name information.
dwRedirectionIDFlags
Determines the validity and content of the redirection party identifier information. The redirection party identifies to the calling user the number toward which diversion was invoked. This member uses the following LINECALLPARTYID_ constants:
LINECALLPARTYID_BLOCKED
Redirection party identifier information for the call is blocked by the caller, but would otherwise be available.
LINECALLPARTYID_OUTOFAREA
Redirection identifier information for the call is not available as it is not propagated all the way by the network.
LINECALLPARTYID_NAME
The redirection party identifier information for the call is the caller's name (from a table maintained inside the switch). It is provided in the redirection ID name variably sized field.
LINECALLPARTYID_ADDRESS
The redirection party identifier information for the call is the caller's number, and is provided in the redirection identifier variably sized field.
LINECALLPARTYID_PARTIAL
Redirection party identifier information for the call is valid, but is limited to partial number information.
LINECALLPARTYID_UNKNOWN
Redirection identifier information is currently unknown but it can become known later.
LINECALLPARTYID_UNAVAIL
Redirection identifier information is unavailable and cannot become known later.
dwRedirectionIDSize
dwRedirectionIDOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing the redirection party identifier number information.
dwRedirectionIDNameSize
dwRedirectionIDNameOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing the redirection party identifier name information.
dwRedirectingIDFlags
Determines the validity and content of the redirecting party identifier information. The redirecting party identifies to the diverted-to user the party from which diversion was invoked. This member uses the following LINECALLPARTYID_ constants:
LINECALLPARTYID_BLOCKED
Redirecting party identifier information for the call is blocked by the caller, but would otherwise be available.
LINECALLPARTYID_OUTOFAREA
Redirecting identifier information for the call is not available because it is not propagated all the way by the network.
LINECALLPARTYID_NAME
The redirecting party identifier information for the call is the caller's name (from a table maintained inside the switch). It is provided in the redirecting identifier name variably sized field.
LINECALLPARTYID_ADDRESS
The redirecting party identifier information for the call is the caller's number, and is provided in the redirecting identifier variably sized field.
LINECALLPARTYID_PARTIAL
Redirecting party identifier information for the call is valid, but is limited to partial number information.
LINECALLPARTYID_UNKNOWN
Redirecting identifier information is currently unknown, but can become known later.
LINECALLPARTYID_UNAVAIL
Redirecting identifier information is unavailable and cannot become known later.
dwRedirectingIDSize
dwRedirectingIDOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing the redirecting party identifier number information.
dwRedirectingIDNameSize
dwRedirectingIDNameOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing the redirecting party identifier name information.
dwAppNameSize
dwAppNameOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field holding the user-friendly application name of the application that first originated, accepted, or answered the call. This is the name that an application can specify with lineInitialize. If the application specifies no such name, the application's module name is used instead.
dwDisplayableAddressSize
dwDisplayableAddressOffset
The displayable string is used for logging purposes. The information is obtained from LINECALLPARAMS for functions that intiate calls. The TAPI function lineTranslateAddress returns appropriate information to be placed in this member in the dwDisplayableAddressSize and dwDisplayableAddressOffset members of the LINETRANSLATEOUTPUT structure.
dwCalledPartySize
dwCalledPartyOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field holding a user-friendly description of the called party. This information can be specified with TSPI_lineMakeCall and can be optionally specified with the lpCallParams parameter whenever a new call is established. It is useful for call logging purposes.
dwCommentSize
dwCommentOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field holding a comment about the call provided by the application that originated the call using TSPI_lineMakeCall. This information can be optionally specified with the lpCallParams parameter whenever a new call is established.
dwDisplaySize
dwDisplayOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field holding raw display information. Depending on the telephony environment, a service provider can extract functional information from this for presentation into a more functional way.
dwUserUserInfoSize
dwUserUserInfoOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field holding user-user information.
dwHighLevelCompSize
dwHighLevelCompOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field holding high-level compatibility information. The format of this information is specified by other standards (ISDN Q.931).
dwLowLevelCompSize
dwLowLevelCompOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field holding low-level compatibility information. The format of this information is specified by other standards (ISDN Q.931).
dwChargingInfoSize
dwChargingInfoOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field holding charging information. The format of this information is specified by other standards (ISDN Q.931).
dwTerminalModesSize
dwTerminalModesOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device field containing an array with DWORD-sized entries, of type LINETERMMODE_. This array is indexed by terminal identifiers, in the range from zero to dwNumTerminals minus one. Each entry in the array specifies the current terminal modes for the corresponding terminal set with the TSPI_lineSetTerminal function for this call's media stream. Values are:
LINETERMMODE_BUTTONS
Button press events sent from the terminal to the line.
LINETERMMODE_LAMPS
Lamp events sent from the line to the terminal.
LINETERMMODE_DISPLAY
Display information sent from the line to the terminal.
LINETERMMODE_RINGER
Ringer control information sent from the switch to the terminal.
LINETERMMODE_HOOKSWITCH
Hookswitch events sent between the terminal and the line.
LINETERMMODE_MEDIATOLINE
The unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIAFROMLINE
The unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIABIDIRECT
The bidirectional media stream associated with a call on the line and the terminal. Use this value when routing of both unidirectional channels of a call's media stream cannot be controlled independently.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field holding device-specific information.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

The LINECALLINFO data structure contains relatively fixed information about a call. This structure is returned with TSPI_lineGetCallInfo. When information items in this data structure have changed, a LINE_CALLINFO message is sent to the application. A parameter to this message is the information item or field that changed.

The dwAppSpecific member can be used by applications to tag calls by using TSPI_lineSetAppSpecific. This member is uninterpreted by TAPI or service providers. It is initially set to zero.

See Also

LINE_CALLINFO, LINEBEARERMODE_ Constants, LINECALLORIGIN_ Constants, LINECALLPARAMFLAGS_ Constants, LINECALLPARTYID_ Constants, LINECALLREASON_ Constants, LINECALLSTATE_ Constants, LINEDIGITMODE_ Constants, LINEMEDIAMODE_ Constants, LINETERMMODE_ Constants, TSPI_lineGetCallInfo, TSPI_lineSetAppSpecific


LINECALLPARAMS

The LINECALLPARAMS structure describes parameters supplied when making calls with TSPI_lineMakeCall. The LINECALLPARAMS structure is also used as a parameter in other operations. The comments on the right indicate the default values used when this structure is not provided to TSPI_lineMakeCall.

typedef struct linecallparams_tag {  // Defaults:
    DWORD  dwTotalSize;  // ---------

    DWORD  dwBearerMode;  // voice
    DWORD  dwMinRate;  // (3.1kHz)
    DWORD  dwMaxRate;  // (3.1kHz)
    DWORD  dwMediaMode;  // interactiveVoice

    DWORD  dwCallParamFlags;  // 0
    DWORD  dwAddressMode;  // addressID
    DWORD  dwAddressID  // (any available)

    LINEDIALPARAMS DialParams;  // (0, 0, 0, 0)

    DWORD  dwOrigAddressSize;  // 0
    DWORD  dwOrigAddressOffset;

    DWORD  dwDisplayableAddressSize;  // 0
    DWORD  dwDisplayableAddressOffset;

    DWORD  dwCalledPartySize;  // 0
    DWORD  dwCalledPartyOffset;

    DWORD  dwCommentSize;  // 0
    DWORD  dwCommentOffset;

    DWORD  dwUserUserInfoSize;  // 0
    DWORD  dwUserUserInfoOffset;

    DWORD  dwHighLevelCompSize;  // 0
    DWORD  dwHighLevelCompOffset;

    DWORD  dwLowLevelCompSize;  // 0
    DWORD  dwLowLevelCompOffset;

    DWORD  dwDevSpecificSize;  // 0
    DWORD  dwDevSpecificOffset;
} LINECALLPARAMS, FAR *LPLINECALLPARAMS;

Members

dwTotalSize
The total size in bytes allocated to this data structure. This size should be big enough to hold all the fixed and variably sized portions of this data structure.
dwBearerMode
The bearer mode for the call. This member uses the following LINEBEARERMODE_ constants:
LINEBEARERMODE_VOICE
A regular 3.1kHz analog voice grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.
LINEBEARERMODE_SPEECH
Corresponds to G.711 speech transmission on the call. The network can use processing techniques such as analog transmission, echo cancellation and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.
LINEBEARERMODE_MULTIUSE
The multiuse mode defined by ISDN.
LINEBEARERMODE_DATA
The unrestricted data transfer on the call. The data rate is specified separately.
LINEBEARERMODE_ALTSPEECHDATA
The alternate transfer of speech or unrestricted data on the same call (ISDN).
LINEBEARERMODE_NONCALLSIGNALING
Corresponds to a non-call-associated signaling connection from the application to the service provider or switch (treated as a media stream by the Telephony API).
LINEBEARERMODE_PASSTHROUGH
When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 comm functions, for the purpose of configuring or using special features not otherwise supported by the service provider.

If dwBearerMode is not set (is 0), the LINEBEARERMODE_VOICE value is assumed.

dwMinRate
dwMaxRate
The data rate range requested for the call's data stream in bps (bits per second). When making a call, the service provider attempts to provide the highest available rate in the requested range. If a specific data rate is required, both min and max should be set to that value. If an application works best with one rate, but is able the degrade to lower rates, the application specifies these as the max and min rates, respectively.

If dwMaxRate is not set (is 0), the rate is assumed to be the maximum rate supported by device.

dwMediaMode
The expected media mode of the call. This member uses the following LINEMEDIAMODE_ constants:
LINEMEDIAMODE_UNKNOWN
A media stream exists but its mode is not known. This corresponds to a call with an unclassified media type. In typical analog telephony environments, an inbound call's media mode may be unknown until after the call is answered and the media stream is filtered to make a determination.
LINEMEDIAMODE_INTERACTIVEVOICE
The presence of voice energy on the call and the call is treated as an interactive call with humans on both ends.
LINEMEDIAMODE_AUTOMATEDVOICE
The presence of voice energy on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM
A data modem session on the call.
LINEMEDIAMODE_G3FAX
A group 3 fax is being sent or received over the call.
LINEMEDIAMODE_TDD
A TDD (Telephony Devices for the Deaf) session on the call.
LINEMEDIAMODE_G4FAX
A group 4 fax is being sent or received over the call.
LINEMEDIAMODE_DIGITALDATA
Digital data being sent or received over the call.
LINEMEDIAMODE_TELETEX
A teletex session on the call. Teletex is one of the telematic services.
LINEMEDIAMODE_VIDEOTEX
A videotex session on the call. Videotex is one the telematic services.
LINEMEDIAMODE_TELEX
A telex session on the call. Telex is one the telematic services.
LINEMEDIAMODE_MIXED
A mixed session on the call. Mixed is one the ISDN telematic services.
LINEMEDIAMODE_ADSI
An ADSI (Analog Display Services Interface) session on the call.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.

If dwMediaMode is not set (is 0), the LINEMEDIAMODE_INTERACTIVEVOICE value is assumed.

dwCallParamFlags
These flags specify a collection of boolean call setup parameters, of type LINECALLPARAMFLAGS_. Values are:
LINECALLPARAMFLAGS_SECURE
The call is set up as secure.
LINECALLPARAMFLAGS_IDLE
The call gets an idle call appearance.
LINECALLPARAMFLAGS_BLOCKID
The originator identity is concealed (block caller ID).
LINECALLPARAMFLAGS_ORIGOFFHOOK
The originator's phone is automatically taken off hook.
LINECALLPARAMFLAGS_DESTOFFHOOK
The called party's phone is automatically taken off hook.
dwAddressMode
The mode by which the originating address is specified, of type LINEADDRESSMODE_. Values are:
LINEADDRESSMODE_ADDRESSID
The address is specified by means of a small integer in the range from 0 to dwNumAddresses minus one, where dwNumAddresses is the value in the line's device capabilities. The selected address is specified in the dwAddressID member.
LINEADDRESSMODE_DIALABLEADDR
The address is specified with its dialable address. The address is contained in the dwOrigAddressSize, dwOrigAddressOffset variably sized field.

If dwAddressMode is not set (is 0), the LINEADDRESSMODE_ADDRESSID value is assumed.

dwAddressID
The address identifier of the originating address if dwAddressMode is set to LINEADDRESSMODE_ADDRESSID.
DialParams
Dial parameters to be used on this call, of type LINEDIALPARAMS. When any member within this field has a value of 0, the default value for the field is used as specified in DefaultDialParams of the LINEDEVCAPS structure. If a nonzero value is specified for a field but the value is outside the range specified by the corresponding fields in MinDialParams and MaxDialParams in the LINEDEVCAPS structure, the nearest value within the valid range is used instead.
dwOrigAddressSize
dwOrigAddressOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field holding the originating address. The format of this address depends on the dwAddressMode member.
dwDisplayableAddressSize
dwDisplayableAddressOffset
The displayable string is used for logging purposes. The content of these fields is recorded in the dwDisplayableAddressSize/Offset member of the call's LINE_CALLINFO message. This information is intended for logging purposes. The TAPI function lineTranslateAddress returns appropriate information to be placed in this field in the dwDisplayableAddressSize/Offset members of the LINETRANSLATEOUTPUT structure.
dwCalledPartySize
dwCalledPartyOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field holding called party information. This information can be specified by the application that makes the call and is made available in the call's information structure for logging purposes. The format of this member is that of dwStringFormat, as specified in LINEDEVCAPS.
dwCommentSize
dwCommentOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field holding comments about the call. This information can be specified by the application that makes the call and is made available in the call's information structure for logging purposes. The format of this member is that of dwStringFormat, as specified in LINEDEVCAPS.
dwUserUserInfoSize
dwUserUserInfoOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field holding user-user information.
dwHighLevelCompSize
dwHighLevelCompOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field holding high-level compatibility information.
dwLowLevelCompSize
dwLowLevelCompOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field holding low-level compatibility information.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field holding device-specific information.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

This structure is used as a parameter for other operations, such as TSPI_lineMakeCall when setting up a call. Its members allow the application to specify the quality of service requested from the network as well as a variety of ISDN call setup parameters. If no LINECALLPARAMS structure is supplied to TSPI_lineMakeCall, a default POTS voice grade call is requested with the default values listed above.

Note that the parameters DialParams through dwDevSpecificOffset are ignored when an lpCallParams parameter is specified with the function TSPI_lineConditionalMediaDetection.

See Also

LINEBEARERMODE_ Constants, LINECALLPARAMFLAGS_ Constants, LINEMEDIAMODE_ Constants, TSPI_lineMakeCall


LINECALLSTATUS

The LINECALLSTATUS structure describes the current status of a call. The information in this structure, as returned with TSPI_lineGetCallStatus, depends on the device capabilities of the address, the ownership of the call by the invoking application, and the current state of the call being queried.

typedef struct linecallstatus_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwCallState;
    DWORD  dwCallStateMode;
    DWORD  dwCallPrivilege;
    DWORD  dwCallFeatures;

    DWORD  dwDevSpecificSize;
    DWORD  dwDevSpecificOffset;
} LINECALLSTATUS, FAR *LPLINECALLSTATUS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold all returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwCallState
dwCallStateMode
The dwCallState member specifies the current call state of the call, of type LINECALLSTATE_. The interpretation of this member is call-state dependent. It specifies the current mode of the call while in its current state (if that state defines a mode).
LINECALLSTATE_IDLE
Call state mode is unused.
LINECALLSTATE_OFFERING
Call state mode is unused.
LINECALLSTATE_ACCEPTED
Call state mode is unused.
LINECALLSTATE_DIALTONE
The call state mode is of type LINEDIALTONEMODE_. Values are:
LINEDIALTONEMODE_NORMAL
A normal dial tone, typically a continuous tone.
LINEDIALTONEMODE_SPECIAL
A special dial tone indicating a certain condition is currently in effect.
LINEDIALTONEMODE_INTERNAL
An internal dial tone, as within a PBX.
LINEDIALTONEMODE_EXTERNAL
An external (public network) dial tone.
LINEDIALTONEMODE_UNKNOWN
The dial tone mode is currently unknown, but can become known later.
LINEDIALTONEMODE_UNAVAIL
The dial tone mode is unavailable and cannot become known.
LINECALLSTATE_DIALING
Call state mode is unused.
LINECALLSTATE_RINGBACK
Call state mode is unused.
LINECALLSTATE_BUSY
The call state mode is of type LINEBUSYMODE_. Values are:
LINEBUSYMODE_STATION
The busy signal indicates that the called party's station is busy. This is usually signaled by means of a normal busy tone.
LINEBUSYMODE_TRUNK
The busy signal indicates that a trunk or circuit is busy. This is usually signaled by means of a long busy tone.
LINEBUSYMODE_UNKNOWN
The busy signal's specific mode is currently unknown, but can become known later.
LINEBUSYMODE_UNAVAIL
The busy signal's specific mode is unavailable and cannot become known.
LINECALLSTATE_SPECIALINFO
The call state mode is of type LINESPECIALINFO_. Values are:
LINESPECIALINFO_NOCIRCUIT
This special information tone precedes a no-circuit or emergency announcement (trunk blockage category).
LINESPECIALINFO_CUSTIRREG
This special information tone precedes a vacant number, AIS, Centrex number change and nonworking station, access code not dialed or dialed in error, or manual intercept operator message (customer irregularity category).
LINESPECIALINFO_REORDER
This special information tone precedes a reorder announcement (equipment irregularity category).
LINESPECIALINFO_UNKNOWN
Specifics about the special information tone are currently unknown but can become known later.
LINESPECIALINFO_UNAVAIL
Specifics about the special information tone are unavailable, and cannot become known.
LINECALLSTATE_CONNECTED
Call state mode is unused.
LINECALLSTATE_PROCEEDING
Call state mode is unused.
LINECALLSTATE_ONHOLD
Call state mode is unused.
LINECALLSTATE_CONFERENCED
Call state mode is unused.
LINECALLSTATE_ONHOLDPENDCONF
Call state mode is unused.
LINECALLSTATE_ONHOLDPENDTRANSFER
Call state mode is unused.
LINECALLSTATE_DISCONNECTED
Call state mode is of type LINEDISCONNECTMODE_. Values are:
LINEDISCONNECTMODE_NORMAL
This is a normal disconnect request by the remote party, the call was terminated normally.
LINEDISCONNECTMODE_UNKNOWN
The reason for the disconnect request is unknown.
LINEDISCONNECTMODE_REJECT
The remote user has rejected the call.
LINEDISCONNECTMODE_PICKUP
The call was picked up from elsewhere.
LINEDISCONNECTMODE_FORWARDED
The call was forwarded by the switch.
LINEDISCONNECTMODE_BUSY
The remote user's station is busy.
LINEDISCONNECTMODE_NOANSWER
The remote user's station does not answer.
LINEDISCONNECTMODE_BADADDRESS
The destination address in invalid.
LINEDISCONNECTMODE_CONGESTION
The network is congested.
LINEDISCONNECTMODE_INCOMPATIBLE
The remote user's station equipment is incompatible for the type of call requested.
LINEDISCONNECTMODE_UNAVAIL
The reason for the disconnect is unavailable and cannot become known later.
LINEDISCONNECTMODE_NODIALTONE
A dial tone was not detected within a service-provider defined timeout, at a point during dialing when one was expected (such as at a "W" in the dialable string). This can also occur without a service-provider-defined timeout period or without a value specified in the dwWaitForDialTone member of the LINEDIALPARAMS structure.
LINECALLSTATE_UNKNOWN
Call state mode is unused.
dwCallPrivilege
The application's privilege for this call, of type LINECALLPRIVILEGE. Values are:
LINECALLPRIVILEGE_MONITOR
The application has monitor privilege.
LINECALLPRIVILEGE_OWNER
The application has owner privilege.
dwCallFeatures
These flags indicate which Telephony API functions can be invoked on the call given the availability of the feature in the device capabilities, the current call state, and call ownership of the invoking application. A zero indicates the corresponding feature cannot be invoked by the application on the call in its current state; a one indicates the feature can be invoked. This member uses the following LINECALLFEATURE_ constants.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device-specific field.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

The application is sent a LINE_CALLSTATE message whenever the call state of a call changes. This message only provides the new call state of the call. Additional status about a call is available through TSPI_lineGetCallStatus.

See Also

LINE_CALLSTATE, LINEBUSYMODE_ Constants, LINECALLFEATURE_ Constants, LINECALLSTATE_ Constants, .LINEDIALTONEMODE_ Constants, LINEDISCONNECTMODE_ Constants, LINESPECIALINFO_ Constants, TSPI_lineGetCallStatus


LINEDEVCAPS

The LINEDEVCAPS structure describes the capabilities of a line device.

typedef struct linedevcaps_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwProviderInfoSize;
    DWORD  dwProviderInfoOffset;

    DWORD  dwSwitchInfoSize;
    DWORD  dwSwitchInfoOffset;

    DWORD  dwPermanentLineID;
    DWORD  dwLineNameSize;
    DWORD  dwLineNameOffset;
    DWORD  dwStringFormat;
    DWORD  dwAddressModes;
    DWORD  dwNumAddresses;
    DWORD  dwBearerModes;
    DWORD  dwMaxRate;
    DWORD  dwMediaModes;

    DWORD  dwGenerateToneModes;
    DWORD  dwGenerateToneMaxNumFreq;
    DWORD  dwGenerateDigitModes;
    DWORD  dwMonitorToneMaxNumFreq;
    DWORD  dwMonitorToneMaxNumEntries;
    DWORD  dwMonitorDigitModes;
    DWORD  dwGatherDigitsMinTimeout;
    DWORD  dwGatherDigitsMaxTimeout;

    DWORD  dwMedCtlDigitMaxListSize;
    DWORD  dwMedCtlMediaMaxListSize;
    DWORD  dwMedCtlToneMaxListSize;
    DWORD  dwMedCtlCallStateMaxListSize;

    DWORD  dwDevCapFlags;
    DWORD  dwMaxNumActiveCalls;
    DWORD  dwAnswerMode;
    DWORD  dwRingModes;
    DWORD  dwLineStates;

    DWORD  dwUUIAcceptSize;
    DWORD  dwUUIAnswerSize;
    DWORD  dwUUIMakeCallSize;
    DWORD  dwUUIDropSize;
    DWORD  dwUUISendUserUserInfoSize;
    DWORD  dwUUICallInfoSize;

    LINEDIALPARAMS  MinDialParams;
    LINEDIALPARAMS  MaxDialParams;
    LINEDIALPARAMS  DefaultDialParams;

    DWORD  dwNumTerminals;
    DWORD  dwTerminalCapsSize;
    DWORD  dwTerminalCapsOffset;
    DWORD  dwTerminalTextEntrySize;
    DWORD  dwTerminalTextSize;
    DWORD  dwTerminalTextOffset;

    DWORD  dwDevSpecificSize;
    DWORD  dwDevSpecificOffset;

} LINEDEVCAPS, FAR *LPLINEDEVCAPS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwProviderInfoSize
dwProviderInfoOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing service provider information.

The dwProviderInfoSize/Offset member provides information about the provider hardware or software, such as the vendor name and version numbers of hardware or software. This information can be useful when a user needs to call customer service with problems regarding the provider.

dwSwitchInfoSize
dwSwitchInfoOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device field containing switch information.

The dwSwitchInfoSize/Offset member is intended to provide information about the switch to which the line device is connected, such as the switch manufacturer, the model name, the software version, and so on. This information can be useful when a user needs to call customer service with problems regarding the switch.

dwPermanentLineID
The permanent DWORD identifier by which the line device is known in the system's configuration. It is a permanent name for the line device. This permanent name (as opposed to dwDevice ID) does not change as lines are added and removed from the system. It can therefore be used to link line-specific information in the registry (or other files) in a way that is not affected by adding or removing other lines.
dwLineNameSize
dwLineNameOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device field containing a user-configurable name for this line device. This name can be configured by the user when configuring the line device's service provider and is provided for the user's convenience.
dwStringFormat
The string format used with this line device, of type STRINGFORMAT_. Values are:
STRINGFORMAT_ASCII
ASCII string format using one byte per character.
STRINGFORMAT_DBCS
DBCS string format using two bytes per character.
STRINGFORMAT_UNICODE
Unicode string format using two bytes per character.
dwAddressModes
The mode by which the originating address is specified, of type LINEADDRESSMODE_. Values are:
LINEADDRESSMODE_ADDRESSID
The address is specified using a small integer in the range from 0 through dwNumAddresses minus one, where dwNumAddresses is the value in the line's device capabilities.
LINEADDRESSMODE_DIALABLEADDR
The address is specified through its phone number.
dwNumAddresses
The number of addresses associated with this line device. Individual addresses are referred to by address identifiers. Address identifiers range from zero to one less than the value indicated by dwNumAddresses.
dwBearerModes
Flag array that indicates the different bearer modes the address is able to support. This member uses the following LINEBEARERMODE_ constants:
LINEBEARERMODE_VOICE
A regular 3.1 kHz analog voice grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.
LINEBEARERMODE_SPEECH
Corresponds to G.711 speech transmission on the call. The network can use processing techniques such as analog transmission, echo cancellation and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.
LINEBEARERMODE_MULTIUSE
The multiuse mode defined by ISDN.
LINEBEARERMODE_DATA
The unrestricted data transfer on the call. The data rate is specified separately. In particular, when LINEBEARERMODE_DATA is set, dwMaxRate indicates the maximum rate of digital transmission on the bearer channel.
LINEBEARERMODE_ALTSPEECHDATA
The alternate transfer of speech or unrestricted data on the same call (ISDN).
LINEBEARERMODE_NONCALLSIGNALING
Corresponds to a non-call-associated signaling connection from the application to the service provider or switch (treated as a "media stream" by the Telephony API).
LINEBEARERMODE_PASSTHROUGH
When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 comm functions, for the purpose of configuring or using special features not otherwise supported by the service provider.
dwMaxRate
Contains the maximum data rate in bits per second for information exchange over the call. If LINEBEARERMODE_DATA is set in dwBearerModes, then dwMaxRate is set to the maximum rate of digital transmission on the bearer channel. If LINEBEARERMODE_DATA is not set, but LINEBEARERMODE_VOICE is set and dwMediaModes includes LINEMEDIAMODE_DATAMODEM, then dwMaxRate is set to the maximum synchronous bit rate of the modulated data signal, not including gains from error control or data compression, and not considering the impact of adaption to channel characteristics (e.g., a V.34 modem would say 28800, a V 32bis modem 14400, a V.32 modem 9600). The application must be careful to check to see that LINEBEARERMODE_DATA is not set, in order to avoid misinterpreting the dwMaxRate member (it is likely to be 64000 or higher if LINEBEARERMODE_DATA is set).
dwMediaModes
Flag array that indicates the different media modes the address is able to support, of type LINEMEDIAMODE_.
LINEMEDIAMODE_UNKNOWN
A media stream exists but its mode is unknown. This corresponds to a call with an unclassified media type. In typical analog telephony environments, an inbound call's media mode may be unknown until after the call is answered and the media stream is filtered to make a determination.
LINEMEDIAMODE_INTERACTIVEVOICE
The presence of voice energy on the call and the call is treated as an interactive call with humans on both ends.
LINEMEDIAMODE_AUTOMATEDVOICE
The presence of voice energy on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM
A data modem session on the call.
LINEMEDIAMODE_G3FAX
A group 3 fax is being sent or received over the call.
LINEMEDIAMODE_TDD
A TDD (Telephony Devices for the Deaf) session on the call.
LINEMEDIAMODE_G4FAX
A group 4 fax is being sent or received over the call.
LINEMEDIAMODE_DIGITALDATA
Digital data being transmitted over the call.
LINEMEDIAMODE_TELETEX
A teletex session on the call. Teletex is one of the telematic services.
LINEMEDIAMODE_VIDEOTEX
A videotex session on the call. Videotex is one the telematic services.
LINEMEDIAMODE_TELEX
A telex session on the call. Telex is one the telematic services.
LINEMEDIAMODE_MIXED
A mixed session on the call. Mixed is one the ISDN telematic services.
LINEMEDIAMODE_ADSI
An ADSI (Analog Display Services Interface) session on the call.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.
dwGenerateToneModes
Specifies the different kinds of tones that can be generated on this line, of type LINETONEMODE_. Values are:
LINETONEMODE_CUSTOM
The tone is a custom tone, defined by the specified frequencies.
LINETONEMODE_RINGBACK
The tone to be generated is ringback tone.
LINETONEMODE_BUSY
The tone is a standard (station) busy tone.
LINETONEMODE_BEEP
The tone is a beep, as used to announce the beginning of a recording.
LINETONEMODE_BILLING
The tone is a billing information tone such as a credit card prompt tone.
dwGenerateToneMaxNumFreq
Contains the maximum number of frequencies that can be specified in describing a general tone using the LINEGENERATETONE data structure when generating a tone using TSPI_lineGenerateTone. A value of zero indicates that tone generation is not available.
dwGenerateDigitModes
The digit modes than can be generated on this line, of type LINEDIGITMODE_. Values are:
LINEDIGITMODE_PULSE
Generate digits as pulse/rotary pulse sequences.
LINEDIGITMODE_DTMF
Generate digits as DTMF tones.
dwMonitorToneMaxNumFreq
Contains the maximum number of frequencies that can be specified in describing a general tone using the LINEMONITORTONE data structure when monitoring a general tone using TSPI_lineMonitorTones. A value of zero indicates that tone monitor is not available.
dwMonitorToneMaxNumEntries
Contains the maximum number of entries that can be specified in a tone list to TSPI_lineMonitorTones.
dwMonitorDigitModes
The digit modes than can be detected on this line, of type LINEDIGITMODE_. Values are:
LINEDIGITMODE_PULSE
Detect digits as audible clicks that are the result of rotary pulse sequences.
LINEDIGITMODE_DTMF
Detect digits as DTMF tones.
LINEDIGITMODE_DTMFEND
Detect down edges of digits detected as DTMF tones.
dwGatherDigitsMinTimeout
dwGatherDigitsMaxTimeout
Contain the minimum and maximum values in milliseconds that can be specified for both the first digit and interdigit timeout values used by TSPI_lineGatherDigits. If both these members are zero, timeouts are not supported.
dwMedCtlDigitMaxListSize
dwMedCtlMediaMaxListSize
dwMedCtlToneMaxListSize
dwMedCtlCallStateMaxListSize
Contain the maximum number of entries that can be specified in the digit list, the media list, the tone list, and the call state list parameters of TSPI_lineSetMediaControl, respectively.
dwDevCapFlags
Specifies various boolean device capabilities, of type LINEDEVCAPFLAGS_. Values are:
LINEDEVCAPFLAGS_CROSSADDRCONF
Specify whether calls on different addresses on this line can be conferenced.
LINEDEVCAPFLAGS_HIGHLEVCOMP
Specify whether high-level compatibility information elements are supported on this line.
LINEDEVCAPFLAGS_LOWLEVCOMP
Specify whether low-level compatibility information elements are supported on this line.
LINEDEVCAPFLAGS_MEDIACONTROL
Specify whether media control operations are available for calls at this line.
LINEDEVCAPFLAGS_MULTIPLEADDR
Specify whether TSPI_lineMakeCall or TSPI_lineDial are able to deal with multiple addresses at once (as for inverse multiplexing).
LINEDEVCAPFLAGS_CLOSEDROP
Specify whether the service provider drops (clears) active calls when all applications have closed the open line. If TRUE, the service provider drops all calls on the line when all applications have closed the line. If FALSE, the service provider keeps calls active. The service provider typically sets this to FALSE if some other device can keep the call alive, for example, if an analog line connects directly to the computer and phoneset in a party-line configuration, the offhook phone automatically keeps the call active even after the computer powers down.
LINEDEVCAPFLAGS_DIALBILLING
LINEDEVCAPFLAGS_DIALQUIET
LINEDEVCAPFLAGS_DIALDIALTONE
These flags indicate whether the "$", "@", or "W" dialable string modifier is supported for a given line device. If the modifier is supported, it is TRUE ; otherwise, FALSE. The "?" (prompt user to continue dialing) is never supported by a line device. These flags allow an application to determine "up front" which modifiers can result in the generation of a LINEERR. The application can pre-scan dialable strings for unsupported characters, or pass the raw string from lineTranslateAddress directly to the provider as part of lineMakeCall (or lineDial) and let the function generate an error to tell it which unsupported modifier occurs first in the string.
dwMaxNumActiveCalls
The maximum number of (minimum bandwidth) calls that can be active (connected) on the line at any one time. The actual number of active calls can be lower if higher bandwidth calls are established on the line.
dwAnswerMode
The effect on the active call when answering another offering call on a line device, of type LINEANSWERMODE_. Values are:
LINEANSWERMODE_NONE
Answering another call on the same has no effect on the existing active call(s) on the line.
LINEANSWERMODE_DROP
The currently active call is automatically dropped.
LINEANSWERMODE_HOLD
The currently active call is automatically placed on hold.
dwRingModes
Contains the number of different ring modes that can be reported in the LINE_LINEDEVSTATE message with the ringing indication. Different ring modes range from one to dwRingModes. Zero indicates no ring.
dwLineStates
Specifies the different line status components for which the application can be notified in a LINE_LINEDEVSTATE message on this line, of type LINEDEVSTATE_. Values are:
LINEDEVSTATE_OTHER
Device-status items other than those listed below have changed.
LINEDEVSTATE_RINGING
The switch tells the line to alert the user. This should be sent repeatedly in a LINE_LINEDEVSTATE message, once for each ring cycle. On a POTS device, the service provider can send the message whenever the central office sends ring voltage. On digital devices such as ISDN, the service provider may need to synthesize the repetition of the message if the switch generates only one ring request. Each repetition of the message should show the ring count increasing, so that toll save functions work properly.
LINEDEVSTATE_CONNECTED
The line was previously disconnected and is now connected to TAPI.
LINEDEVSTATE_DISCONNECTED
This line was previously connected and is now disconnected from TAPI.
LINEDEVSTATE_MSGWAITON
The "message waiting" indicator is turned on.
LINEDEVSTATE_MSGWAITOFF
The "message waiting" indicator is turned off.
LINEDEVSTATE_INSERVICE
The line is connected to TAPI. This happens when TAPI is first activated, or when the line wire is physically plugged in and in service at the switch while TAPI is active.
LINEDEVSTATE_OUTOFSERVICE
The line is out of service at the switch or is physically disconnected. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_MAINTENANCE
Maintenance is being performed on the line at the switch. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_OPEN
The line has been opened.
LINEDEVSTATE_CLOSE
The line has been closed.
LINEDEVSTATE_NUMCALLS
The number of calls on the line device has changed.
LINEDEVSTATE_NUMCOMPLETIONS
The number of outstanding call completions on the line device has changed.
LINEDEVSTATE_TERMINALS
The terminal settings have changed.
LINEDEVSTATE_ROAMMODE
The roam mode of the line device has changed.
LINEDEVSTATE_BATTERY
The battery level has changed significantly (cellular).
LINEDEVSTATE_SIGNAL
The signal level has changed significantly (cellular).
LINEDEVSTATE_DEVSPECIFIC
The line's device-specific information has changed.
LINEDEVSTATE_REINIT
Items have changed in the configuration of line devices. To become aware of these changes (such as for the appearance of new line devices) the application reinitializes its use of TAPI. The hDevice parameter is left NULL for this state change as it applies to any of the lines in the system.
LINEDEVSTATE_LOCK
The locked status of the line device has changed.
LINEDEVSTATE_REMOVED
The device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A LINE_LINEDEVSTATE message with this value is normally immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it to applications that have negotiated this or a subsequent API version; applications negotiating a previous API version do not receive any notification.
dwUUIAcceptSize
The maximum size of user-user information that can be sent during a call accept.
dwUUIAnswerSize
The maximum size of user-user information that can be sent during a call answer.
dwUUIMakeCallSize
The maximum size of user-user information that can be sent during a make call.
dwUUIDropSize
The maximum size of user-user information that can be sent during a call drop.
dwUUISendUserUserInfoSize
The maximum size of user-user information that can be sent separately at any time during a call with TSPI_lineSendUserUserInfo.
dwUUICallInfoSize
The maximum size of user-user information that can be received in the LINECALLINFO structure.
MinDialParams
MaxDialParams
Contain the minimum and maximum values for the dial parameters in milliseconds that can be set for calls on this line. Dialing parameters can be set to values in this range. The granularity of the actual settings are service-provider specific.
DefaultDialParams
Contains the default dial parameters used for calls on this line. These parameter values can be overridden on a per-call basis.
dwNumTerminals
The number of terminals that can be set for this line device, its addresses, or its calls. Individual terminals are referred to by terminal identifiers, and range from zero to one less than the value indicated by dwNumTerminals.
dwTerminalCapsSize
dwTerminalCapsOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device field containing an array with entries of type LINETERMCAPS. This array is indexed by terminal identifiers, in the range from zero to dwNumTerminals minus one. Each entry in the array specifies the terminal device capabilities of the corresponding terminal.
dwTerminalTextEntrySize
The size in bytes of each of the terminal text descriptions pointed at by dwTerminalTextSize/Offset.
dwTerminalTextSize
dwTerminalTextOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field containing descriptive text about each of the line's available terminals. Each message is dwTerminalTextEntrySize bytes long. The string format of these textual descriptions is indicated by dwStringFormat in the line's device capabilities.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device-specific field.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

See Also

LINEADDRESSSHARING_ Constants, LINEBEARERMODE_ Constants, LINEDIGITMODE_ Constants, LINETERMMODE_ Constants, LINEGENERATETONE, LINE_CLOSE, LINE_LINEDEVSTATE, TSPI_lineGetDevCaps


LINEDEVSTATUS

The LINEDEVSTATUS structure describes the current status of a line device.

typedef struct linedevstatus_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwNumOpens;
    DWORD  dwOpenMediaModes;
    DWORD  dwNumActiveCalls;
    DWORD  dwNumOnHoldCalls;
    DWORD  dwNumOnHoldPendCalls;
    DWORD  dwLineFeatures;
    DWORD  dwNumCallCompletions;
    DWORD  dwRingMode;
    DWORD  dwSignalLevel;
    DWORD  dwBatteryLevel;
    DWORD  dwRoamMode;

    DWORD  dwDevStatusFlags;

    DWORD  dwTerminalModesSize;
    DWORD  dwTerminalModesOffset;

    DWORD  dwDevSpecificSize;
    DWORD  dwDevSpecificOffset;
} LINEDEVSTATUS, FAR *LPLINEDEVSTATUS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwNumOpens
The number of active opens on the line device.
dwOpenMediaModes
Bit array that indicates for which media modes the line device is currently open.
dwNumActiveCalls
The number of calls on the line in call states other than idle, onHold, onHoldPendingTransfer, and onHoldPendingConference.
dwNumOnHoldCalls
The number of calls on the line in the onHold state.
dwNumOnHoldPendingCalls
The number of calls on the line in the onHoldPendingTransfer or onHoldPendingConference state.
dwLineFeatures
The line-related API functions that are currently available on this line, of type LINEFEATURE_. Values are:
LINEFEATURE_DEVSPECIFIC
Device-specific operations can be used on the line.
LINEFEATURE_DEVSPECIFICFEAT
Device-specific features can be used on the line.
LINEFEATURE_FORWARD
Forwarding of all addresses can be used on the line.
LINEFEATURE_MAKECALL
An outbound call can be placed on this line using an unspecified address.
LINEFEATURE_SETMEDIACONTROL
Media control can be set on this line.
LINEFEATURE_SETTERMINAL
Terminal modes for this line can be set.
dwNumCallCompletions
The number of outstanding call completion requests on the line.
dwRingMode
The current ring mode on the line device.
dwSignalLevel
The current signal level of the connection on the line. This is value in the range 0x00000000 (weakest signal) to 0x0000FFFF (strongest signal).
dwBatteryLevel
The current battery level of the line device hardware. This is value in the range 0x00000000 (battery empty) to 0x0000FFFF (battery full).
dwRoamMode
The current roam mode of the line device, of type LINEROAMMODE_. Values are:
LINEROAMMODE_UNKNOWN
The roam mode is currently unknown, but can become known later.
LINEROAMMODE_UNAVAIL
The roam mode is unavailable and cannot be known.
LINEROAMMODE_HOME
The line is connected to the home network node.
LINEROAMMODE_ROAMA
The line is connected to the Roam-A carrier and calls are charged accordingly.
LINEROAMMODE_ROAMB
The line is connected to the Roam-B carrier and calls are charged accordingly.
dwDevStatusFlags
The size in bytes of this data structure that contains useful information, of type LINEDEVSTATUSFLAGS_. Values are:
LINEDEVSTATUSFLAGS_CONNECTED
Specify whether the line is connected to TAPI. If TRUE, the line is connected, and API is able to operate on the line device. If FALSE, the line is disconnected, and the application is unable to control the line device through TAPI.
LINEDEVSTATUSFLAGS_MSGWAIT
This field indicates whether the line has a message waiting. If TRUE, a message is waiting; if FALSE, no message is waiting.
LINEDEVSTATUSFLAGS_INSERVICE
Indicate whether the line is in service. If TRUE, the line is in service; if FALSE, the line is out of service.
LINEDEVSTATUSFLAGS_LOCKED
Indicate whether the line is locked or unlocked. This bit is most often used with line devices associated with cellular phones. Many cellular phones have a security mechanism that requires the entry of a password to enable the phone to place calls. This bit can be used to indicate to applications that the phone is locked and cannot place calls until the password is entered on the user interface of the phone, so that the application can present an appropriate alert to the user.
dwTerminalModesSize
dwTerminalModesOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device field containing an array with DWORD-sized entries, of type LINETERMMODE_. This array is indexed by terminal identifiers, in the range from zero to dwNumTerminals minus one. Each entry in the array specifies the current terminal modes for the corresponding terminal set with the TSPI_lineSetTerminal operation for this line. Values are:
LINETERMMODE_BUTTONS
Button press events sent from the terminal to the line.
LINETERMMODE_LAMPS
Lamp events sent from the line to the terminal.
LINETERMMODE_DISPLAY
Display information sent from the line to the terminal.
LINETERMMODE_RINGER
Ringer control information sent from the switch to the terminal.
LINETERMMODE_HOOKSWITCH
Hookswitch events sent between the terminal and the line.
LINETERMMODE_MEDIATOLINE
The unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIAFROMLINE
The unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIABIDIRECT
The bidirectional media stream associated with a call on the line and the terminal. Use this value when routing of both unidirectional channels of a call's media stream cannot be controlled independently.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device-specific field.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

See Also

LINEMEDIAMODE_ Constants, TSPI_lineGetLineDevStatus


LINEDIALPARAMS

The LINEDIALPARAMS structure describes a collection of dialing-related parameters.

typedef struct linedialparams_tag {
    DWORD  dwDialPause;
    DWORD  dwDialSpeed;
    DWORD  dwDigitDuration;
    DWORD  dwWaitForDialtone;
} LINEDIALPARAMS, FAR *LPLINEDIALPARAMS;

Members

dwDialPause
The duration in milliseconds of a comma in the dialable address.
dwDialSpeed
The inter-digit time period in milliseconds between successive digits.
dwDigitDuration
The duration in milliseconds of a digit.
dwWaitForDialtone
The maximum amount of time that should be waited for dialtone when a 'W' is used in the dialable address.

Remarks

Not extensible.

When a value of zero is specified for a field, the service provider uses the default value for that field. If a nonzero value is specified for a field that is outside the range specified by the corresponding fields in MinDialParams and MaxDialParams in the LINEDEVCAPS structure, the service provider uses the nearest value within the valid range.

The LINEDIALPARAMS structure is used to set dialing-related parameters on calls. TSPI_lineMakeCall allows an application to adjust the dialing parameters to be used for the call. TSPI_lineSetCallParams can be used to adjust the dialing parameters of an existing call. The LINECALLINFO structure lists the call's current dialing parameters.

See Also

LINECALLINFO, LINECALLPARAMS, TSPI_lineGetCallInfo, TSPI_lineMakeCall, TSPI_lineSetCallParams


LINEEXTENSIONID

The LINEEXTENSIONID structure describes an extension identifier. Extension identifiers are used to identify service-provider specific extensions for line devices.

typedef struct lineextensionid_tag {
    DWORD  dwExtensionID0;
    DWORD  dwExtensionID1;
    DWORD  dwExtensionID2;
    DWORD  dwExtensionID3;
} LINEEXTENSIONID, FAR *LPLINEEXTENSIONID;

Members

dwExtensionID0
dwExtensionID1
dwExtensionID2
dwExtensionID3
These four DWORD-sized fields together specify a universally unique extension identifier that identifies a line device class extension.

Remarks

Not extensible.

Extension identifiers are generated using an SDK-provided generation utility.

See Also

TSPI_lineGetExtensionID


LINEFORWARD

The LINEFORWARD structure describes an entry of the forwarding instructions.

typedef struct lineforward_tag {
    DWORD  dwForwardMode;

    DWORD  dwCallerAddressSize;
    DWORD  dwCallerAddressOffset;

    DWORD  dwDestCountryCode;
    DWORD  dwDestAddressSize;
    DWORD  dwDestAddressOffset;
} LINEFORWARD, FAR *LPLINEFORWARD;

Members

dwForwardMode
The types of forwarding, of type LINEFORWARDMODE_. The dwForwardMode member can have only a single bit set. Values are:
LINEFORWARDMODE_UNCOND
Forward all calls unconditionally, irrespective of their origin. Use this value when unconditional forwarding for internal and external calls cannot be controlled separately. Unconditional forwarding overrides forwarding on busy or no-answer conditions.
LINEFORWARDMODE_UNCONDINTERNAL
Forward all internal calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.
LINEFORWARDMODE_UNCONDEXTERNAL
Forward all external calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.
LINEFORWARDMODE_UNCONDSPECIFIC
Forward all calls that originated at a specified address unconditionally (selective call forwarding).
LINEFORWARDMODE_BUSY
Forward all calls on busy, irrespective of their origin. Use this value when forwarding for internal and external calls on busy and no answer cannot be controlled separately.
LINEFORWARDMODE_BUSYINTERNAL
Forward all internal calls on busy. Use this value when forwarding for internal and external calls on busy and no answer can be controlled separately.
LINEFORWARDMODE_BUSYEXTERNAL
Forward all external calls on busy. Use this value when forwarding for internal and external calls on busy and no answer can be controlled separately.
LINEFORWARDMODE_BUSYSPECIFIC
Forward all calls that originated at a specified address on busy (selective call forwarding).
LINEFORWARDMODE_NOANSW
Forward all calls on no answer, irrespective of their origin. Use this value when call forwarding for internal and external calls on no answer cannot be controlled separately.
LINEFORWARDMODE_NOANSWINTERNAL
Forward all internal calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.
LINEFORWARDMODE_NOANSWEXTERNAL
Forward all external calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.
LINEFORWARDMODE_NOANSWSPECIFIC
Forward all calls that originated at a specified address on no answer (selective call forwarding).
LINEFORWARDMODE_BUSYNA
Forward all calls on busy/no answer, irrespective of their origin. Use this value when forwarding for internal and external calls on busy and no answer cannot be controlled separately.
LINEFORWARDMODE_BUSYNAINTERNAL
Forward all internal calls on busy/no answer. Use this value when call forwarding on busy and no answer cannot be controlled separately for internal calls.
LINEFORWARDMODE_BUSYNAEXTERNAL
Forward all external calls on busy/no answer. Use this value when call forwarding on busy and no answer cannot be controlled separately for internal calls.
LINEFORWARDMODE_BUSYNASPECIFIC
Forward all calls that originated at a specified address on busy/no answer (selective call forwarding).
dwCallerAddressSize
dwCallerAddressOffset
The size in bytes and the offset from the beginning of the containing data structure in bytes of the variably sized address field containing the address of a caller to be forwarded. The dwCallerAddressSize/Offset member is set to zero if dwForwardMode is not one of the following: LINEFORWARDMODE_BUSYNASPECIFIC, LINEFORWARDMODE_NOANSWSPECIFIC, LINEFORWARDMODE_UNCONDSPECIFIC, or LINEFORWARDMODE_BUSYSPECIFIC.

The offset dwCallerAddressOffset in the variably sized field of type LINEFORWARD pointed at by dwForwardSize/Offset is relative to the beginning of the LINEADDRESSSTATUS data structure (the "root" container).

dwDestCountryCode
The country code of the destination address where the call is to be forwarded.
dwDestAddressSize
dwDestAddressOffset
The size in bytes and the offset from the beginning of the containing data structure in bytes of the variably sized address field containing the address of the address where calls are to be forwarded.

The offset dwDestAddressOffset in the variably sized field of type LINEFORWARD pointed at by dwForwardSize/Offset is relative to the beginning of the LINEADDRESSSTATUS data structure (the "root" container).

Remarks

Not extensible.

Each entry in the LINEFORWARD structure specifies a forwarding request.

See Also

LINE_ADDRESSSTATE, LINECALLORIGIN_ Constants, LINEFORWARDLIST, LINEFORWARDMODE_ Constants, TSPI_lineForward, TSPI_lineGetAddressStatus


LINEFORWARDLIST

The LINEFORWARDLIST structure describes a list of forwarding instructions.

typedef struct lineforwardlist_tag {
    DWORD  dwTotalSize;
    DWORD  dwNumEntries;
    LINEFORWARD  ForwardList[1];
} LINEFORWARDLIST, FAR *LPLINEFORWARDLIST;

Members

dwTotalSize
The total size in bytes of the data structure.
dwNumEntries
Number of entries in the array specified as ForwardList[ ].
ForwardList[ ]
An array of forwarding instructions. The array's entries are of type LINEFORWARD.

Remarks

Not extensible.

The LINEFORWARDLIST structure defines the forwarding parameters requested for forwarding calls on an address or on all addresses on a line.

See Also

LINE_ADDRESSSTATE, LINEFORWARD, TSPI_lineForward, TSPI_lineGetAddressStatus


LINEGENERATETONE

The LINEGENERATETONE structure contains information about a tone to be generated.

typedef struct linegeneratetone_tag {
    DWORD  dwFrequency;
    DWORD  dwCadenceOn;
    DWORD  dwCadenceOff;
    DWORD  dwVolume;
} LINEGENERATETONE, FAR *LPLINEGENERATETONE;

Members

dwFrequency
The frequency in hertz of this tone component. A service provider can adjust (round up or down) the frequency specified by the application to fit its resolution.
dwCadenceOn
Determines the "on" duration in milliseconds of the cadence of the custom tone to be generated. Zero means no tone is generated.
dwCadenceOff
Determines the "off" duration in milliseconds of the cadence of the custom tone to be generated. Zero means no off time, a constant tone.
dwVolume
Determines the volume level at which the tone is to be generated. A value of 0x0000FFFF represents full volume, and a value of 0x00000000 is silence.

Remarks

Not extensible.

This structure is only used for the generation of tones; it is not used for tone monitoring.

See Also

TSPI_lineGenerateTone


LINEMEDIACONTROLCALLSTATE

The LINEMEDIACONTROLCALLSTATE structure describes a media action to be executed when detecting transitions into one or more call states.

typedef struct linemediacontrolcallstate_tag {
    DWORD  dwCallStates;
    DWORD  dwMediaControl;
} LINEMEDIACONTROLCALLSTATE,
FAR *LPLINEMEDIACONTROLCALLSTATE;

Members

dwCallStates
One or more call states, of type LINECALLSTATE_. Values are:
LINECALLSTATE_IDLE
The call is idle; no call actually exists.
LINECALLSTATE_OFFERING
The call is being offered to the station, signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user; alerting is done by the switch instructing the line to ring. It does not affect any call states.
LINECALLSTATE_ACCEPTED
The call was offering and is accepted. This indicates to other (monitoring) applications that the current owner application has claimed responsibility for answering the call. In ISDN, this also initiates alerting to both parties.
LINECALLSTATE_DIALTONE
The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number.
LINECALLSTATE_DIALING
Destination address information (a phone number) is being sent to the switch over the call. Note that the operation TSPI_lineGenerateDigits does not place the line into the dialing state.
LINECALLSTATE_RINGBACK
The call is receiving ringback from the called address. Ringback indicates that the other station has been reached and is being alerted.
LINECALLSTATE_BUSY
The call is receiving a busy tone. Busy tone indicates that the call cannot be completed because either a circuit (trunk) or the remote party's station are in use.
LINECALLSTATE_SPECIALINFO
Special information is sent by the network. Special information is typically sent when the destination cannot be reached.
LINECALLSTATE_CONNECTED
The call has been established, the connection is made. Information is able to flow over the call between the originating address and the destination address.
LINECALLSTATE_PROCEEDING
Dialing has completed and the call is proceeding through the switch or telephone network.
LINECALLSTATE_ONHOLD
The call is on hold by the switch.
LINECALLSTATE_CONFERENCED
The call is currently a member of a multiparty conference call.
LINECALLSTATE_ONHOLDPENDCONF
The call is currently on hold while it is being added to a conference.
LINECALLSTATE_ONHOLDPENDTRANSFER
The call is currently on hold awaiting transfer to another number.
LINECALLSTATE_DISCONNECTED
The remote party has disconnected from the call.
LINECALLSTATE_UNKNOWN
The state of the call is not known. This can be due to limitations of the call progress detection implementation.
dwMediaControl
The media control action, of type LINEMEDIACONTROL_. Values are:
LINEMEDIACONTROL_NONE
No change is to be made to the media stream.
LINEMEDIACONTROL_START
Start the media stream.
LINEMEDIACONTROL_RESET
Reset the media stream. Provide the effect of an end of input. All buffers are released.
LINEMEDIACONTROL_PAUSE
Temporarily pause the media stream.
LINEMEDIACONTROL_RESUME
Start or resume a paused media stream.
LINEMEDIACONTROL_RATEUP
The speed of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_RATEDOWN
The speed of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_RATENORMAL
The speed of the media stream is returned to normal.
LINEMEDIACONTROL_VOLUMEUP
The amplitude of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMEDOWN
The amplitude of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMENORMAL
The amplitude of the media stream is returned to normal.

Remarks

Not extensible.

The LINEMEDIACONTROLCALLSTATE structure defines a triple <call state(s), media control action>. An array of these triples is passed to the TSPI_lineSetMediaControl function to set media control actions triggered by the transition to the call state of the given call. When a transition to a listed call state is detected, the corresponding action on the media stream is invoked.

See Also

LINE_CALLSTATE, LINECALLSTATE_ Constants, LINEMEDIACONTROL_ Constants, TSPI_lineSetMediaControl


LINEMEDIACONTROLDIGIT

The LINEMEDIACONTROLDIGIT structure describes a media action to be executed when detecting a digit. It is used as as entry in an array.

typedef struct linemediacontroldigit_tag {
    DWORD      dwDigit;
    DWORD      dwDigitModes;
    DWORD      dwMediaControl;
} LINEMEDIACONTROLDIGIT, FAR *LPLINEMEDIACONTROLDIGIT;

Members

dwDigit
The low-order byte of this DWORD specifies the digit in ASCII whose detection is to trigger a media action. Valid digits depend on the media mode.
dwDigitModes
The digit modes that are to be monitored, of type LINEDIGITMODE_. Values are:
LINEDIGITMODE_PULSE
Detect digits as audible clicks that are the result of rotary pulse sequences. Valid digits for pulse are '0' through '9'.
LINEDIGITMODE_DTMF
Detect digits as DTMF tones. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.
LINEDIGITMODE_DTMFEND
Detect and provide application notification of DTMF down edges. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.
dwMediaControl
The media control action, of type LINEMEDIACONTROL_. Values are:
LINEMEDIACONTROL_NONE
Make no change to the media stream.
LINEMEDIACONTROL_START
Start the media stream.
LINEMEDIACONTROL_RESET
Reset the media stream. Provide the effect of an end of input. All buffers are released.
LINEMEDIACONTROL_PAUSE
Temporarily pause the media stream.
LINEMEDIACONTROL_RESUME
Start or resume a paused media stream.
LINEMEDIACONTROL_RATEUP
The speed of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_RATEDOWN
The speed of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_RATENORMAL
The speed of the media stream is returned to normal.
LINEMEDIACONTROL_VOLUMEUP
The amplitude of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMEDOWN
The amplitude of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMENORMAL
The amplitude of the media stream is returned to normal.

Remarks

Not extensible.

The LINEMEDIACONTROLMEDIA structure defines a triple <digit, digit mode(s), media control action>. An array of these triples is passed to the TSPI_lineSetMediaControl function to set media control actions triggered by digits detected on a given call. When a listed digit is detected, the corresponding action on the media stream is invoked.

See Also

LINEDIGITMODE_ Constants, LINEMEDIACONTROL_ Constants, TSPI_lineSetMediaControl


LINEMEDIACONTROLMEDIA

The LINEMEDIACONTROLMEDIA structure describes a media action to be executed when a media mode change is detected. It is used as as entry in an array.

typedef struct linemediacontrolmedia_tag {
    DWORD      dwMediaModes;
    DWORD      dwDuration;
    DWORD      dwMediaControl;
} LINEMEDIACONTROLMEDIA, FAR *LPLINEMEDIACONTROLMEDIA;

Members

dwMediaModes
One or more media modes, of type LINEMEDIAMODE_. Values are:
LINEMEDIAMODE_INTERACTIVEVOICE
The presence of voice energy on the call and the call is treated as an interactive call with humans on both ends.
LINEMEDIAMODE_AUTOMATEDVOICE
The presence of voice energy on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM
A data modem session on the call.
LINEMEDIAMODE_G3FAX
A group 3 fax is being sent or received over the call.
LINEMEDIAMODE_TDD
A TDD (Telephony Devices for the Deaf) session on the call.
LINEMEDIAMODE_G4FAX
A group 4 fax is being sent or received over the call.
LINEMEDIAMODE_DIGITALDATA
Digital data is being sent or received over the call.
LINEMEDIAMODE_TELETEX
A teletex session on the call. Teletex is one of the telematic services.
LINEMEDIAMODE_VIDEOTEX
A videotex session on the call. Videotex is one the telematic services.
LINEMEDIAMODE_TELEX
A telex session on the call. Telex is one the telematic services.
LINEMEDIAMODE_MIXED
A mixed session on the call. Mixed is one the ISDN telematic services.
LINEMEDIAMODE_ADSI
An ADSI (Analog Display Services Interface) session on the call.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.
dwDuration
The duration in milliseconds during which the media mode is present before the application is notified or media control action is taken.
dwMediaControl
The media control action, of type LINEMEDIACONTROL_. Values are:
LINEMEDIACONTROL_NONE
Make no change to the media stream.
LINEMEDIACONTROL_START
Start the media stream.
LINEMEDIACONTROL_RESET
Reset the media stream. Provide the effect of an end of input. All buffers are released.
LINEMEDIACONTROL_PAUSE
Temporarily pause the media stream.
LINEMEDIACONTROL_RESUME
Start or resume a paused media stream.
LINEMEDIACONTROL_RATEUP
The speed of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_RATEDOWN
The speed of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_RATENORMAL
The speed of the media stream is returned to normal.
LINEMEDIACONTROL_VOLUMEUP
The amplitude of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMEDOWN
The amplitude of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMENORMAL
The amplitude of the media stream is returned to normal.

Remarks

Not extensible.

The LINEMEDIACONTROLMEDIA structure defines a triple <media mode(s), duration, media control action>. An array of these triples is passed to the TSPI_lineSetMediaControl function to set media control actions triggered by media mode changes for a given call. When a change to a listed media mode is detected, the corresponding action on the media stream is invoked.

See Also

LINEMEDIACONTROL_ Constants, LINEMEDIAMODE_ Constants, TSPI_lineSetMediaControl


LINEMEDIACONTROLTONE

The LINEMEDIACONTROLTONE structure describes a media action to be executed when a tone is detected. It is used as as entry in an array.

typedef struct linemediacontroltone_tag {
    DWORD  dwAppSpecific;
    DWORD  dwDuration;
    DWORD  dwFrequency1;
    DWORD  dwFrequency2;
    DWORD  dwFrequency3;
    DWORD  dwMediaControl;
} LINEMEDIACONTROLTONE, FAR *LPLINEMEDIACONTROLTONE;

Members

dwAppSpecific
Used by the application for tagging the tone. When this tone is detected, the value of the dwAppSpecific member is passed back to the application.
dwDuration
The duration in milliseconds during which the tone is present before a detection is made.
dwFrequency1
dwFrequency2
dwFrequency3
The frequency in hertz of a component of the tone. If fewer than three frequencies are needed in the tone, a value of zero should be used for the unused frequencies. A tone with all three frequencies set to zero is interpreted as silence, and can be used for silence detection.
dwMediaControl
The media control action, of type LINEMEDIACONTROL_. Values are:
LINEMEDIACONTROL_NONE
Make no change to the media stream.
LINEMEDIACONTROL_START
Start the media stream.
LINEMEDIACONTROL_RESET
Reset the media stream. Provide the effect of an end of input. All buffers are released.
LINEMEDIACONTROL_PAUSE
Temporarily pause the media stream.
LINEMEDIACONTROL_RESUME
Start or resume a paused media stream.
LINEMEDIACONTROL_RATEUP
The speed of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_RATEDOWN
The speed of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_RATENORMAL
The speed of the media stream is returned to normal.
LINEMEDIACONTROL_VOLUMEUP
The amplitude of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMEDOWN
The amplitude of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMENORMAL
The amplitude of the media stream is returned to normal.

Remarks

Not extensible.

The LINEMEDIACONTROLTONE structure defines a tuple <tone, media control action>. An array of these tuples is passed to the TSPI_lineSetMediaControl function to set media control actions triggered by media mode changes for a given call. When a change to a listed media mode is detected, the corresponding action on the media stream is invoked.

A tone with all frequencies set to zero corresponds to silence. An application can thus monitor the call's information stream for silence.

See Also

LINEMEDIACONTROL_ Constants, TSPI_lineSetMediaControl


LINEMONITORTONE

The LINEMONITORTONE structure describes a tone to be monitored. This is used as an entry in an array.

typedef struct linemonitortone_tag {
    DWORD  dwAppSpecific;
    DWORD  dwDuration;
    DWORD  dwFrequency1;
    DWORD  dwFrequency2;
    DWORD  dwFrequency3;
} LINEMONITORTONE, FAR *LPLINEMONITORTONE;

Members

dwAppSpecific
Used by the application for tagging the tone. When this tone is detected, the value of the dwAppSpecific member is passed back to the application.
dwDuration
The duration in milliseconds during which the tone should be present before a detection is made.
dwFrequency1
dwFrequency2
dwFrequency3
The frequency in hertz of a component of the tone. If fewer than three frequencies are needed in the tone, a value of zero should be used for the unused frequencies. A tone with all three frequencies set to zero is interpreted as silence, and can be used for silence detection.

Remarks

Not extensible.

The LINEMONITORTONE structure defines a tone for the purpose of detection. An array of tones is passed to the TSPI_lineMonitorTones function, which monitors these tones and sends a LINE_MONITORTONE message to the application when a detection is made.

A tone with all frequencies set to zero corresponds to silence. An application can thus monitor the call's information stream for silence.

See Also

TSPI_lineMonitorTones


LINETERMCAPS

The LINETERMCAPS structure describes the capabilities of a line's terminal device.

typedef struct linetermcaps_tag {
    DWORD  dwTermDev;
    DWORD  dwTermModes;
    DWORD  dwTermSharing;
} LINETERMCAPS, FAR *LPLINETERMCAPS;

Members

dwTermDev
The device type of the terminal, of type LINETERMDEV_. Values are:
LINETERMDEV_PHONE
The terminal is a phone set.
LINETERMDEV_HEADSET
The terminal is a headset.
LINETERMDEV_SPEAKER
The terminal is an external speaker and microphone.
dwTermModes
The terminal modes that the terminal device is able to deal with, of type LINETERMMODE_. Values are:
LINETERMMODE_BUTTONS
Button press events sent from the terminal to the line.
LINETERMMODE_LAMPS
Lamp events sent from the line to the terminal.
LINETERMMODE_DISPLAY
Display information sent from the line to the terminal.
LINETERMMODE_RINGER
Ringer control information sent from the switch to the terminal.
LINETERMMODE_HOOKSWITCH
Hookswitch events sent from the terminal to the line.
LINETERMMODE_MEDIATOLINE
The unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIAFROMLINE
The unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIABIDIRECT
The bidirectional media stream associated with a call on the line and the terminal. Use this value when routing of both unidirectional channels of a call's media stream cannot be controlled independently.
dwTermSharing
Specifies how the terminal device is shared between line devices, of type LINETERMSHARING_. Values are:
LINETERMSHARING_PRIVATE
The terminal device is private to a single line device.
LINETERMSHARING_SHAREDEXCL
The terminal device can be used by multiple lines. The last line device to do a TSPI_lineSetTerminal to the terminal for a given terminal mode has exclusive connection to the terminal for that mode.
LINETERMSHARING_SHAREDCONF
The terminal device can be used by multiple lines. The TSPI_lineSetTerminal requests of the various terminals end up merged at the terminal.

Remarks

Not extensible.

See Also

LINEDEVCAPS


TSPI Phone Device Structures

Note Some structures include Size and Offset fields for defining the location and length of strings in the variable portion of the structure. If the service provider is requested to add a string but no string is available, the service provider must indicate this condition in one of the following ways:

  • Set both the Size and Offset fields to 0.
  • Set the Offset field to nonzero, but set Size to 0.
  • Set the Offset field to nonzero, set Size 1, and the set the byte at the Offset to 0.


PHONEBUTTONINFO

The PHONEBUTTONINFO structure contains information about a button on a phone device.

typedef struct phonebuttoninfo_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwButtonMode;
    DWORD  dwButtonFunction;

    DWORD  dwButtonTextSize;
    DWORD  dwButtonTextOffset;

    DWORD  dwDevSpecificSize;
    DWORD  dwDevSpecificOffset;
} PHONEBUTTONINFO, FAR *LPPHONEBUTTONINFO;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwButtonMode
The mode or general usage class of the button. This member uses the following PHONEBUTTONMODE_ constants:
PHONEBUTTONMODE_DUMMY
This value is used to describe a button/lamp position that has no corresponding button, but has only a lamp.
PHONEBUTTONMODE_CALL
The button is assigned to a call appearance.
PHONEBUTTONMODE_FEATURE
The button is assigned to requesting features from the switch, such as hold, conference, and transfer.
PHONEBUTTONMODE_KEYPAD
The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'.
PHONEBUTTONMODE_LOCAL
The button is a local function button, such as mute or volume control.
PHONEBUTTONMODE_DISPLAY
The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.
dwButtonFunction
The function assigned to the button. This member uses the PHONEBUTTONFUNCTION_ constants (not listed here).
dwButtonTextSize
dwButtonTextOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing descriptive text for this button. The format of this information is as specified in the dwStringFormat member of the phone's device capabilities.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device-specific field.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

See Also

PHONEBUTTONFUNCTION_ Constants, PHONEBUTTONMODE_ Constants, TSPI_phoneGetButtonInfo, TSPI_phoneSetButtonInfo


PHONECAPS

The PHONECAPS structure describes the capabilities of a phone device.

typedef struct phonecaps_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwProviderInfoSize;
    DWORD  dwProviderInfoOffset;

    DWORD  dwPhoneInfoSize;
    DWORD  dwPhoneInfoOffset;

    DWORD  dwPermanentPhoneID;
    DWORD  dwPhoneNameSize;
    DWORD  dwPhoneNameOffset;
    DWORD  dwStringFormat;

    DWORD  dwPhoneStates;
    DWORD  dwHookSwitchDevs;
    DWORD  dwHandsetHookSwitchModes;
    DWORD  dwSpeakerHookSwitchModes;
    DWORD  dwHeadsetHookSwitchModes;

    DWORD  dwVolumeFlags;
    DWORD  dwGainFlags;
    DWORD  dwDisplayNumRows;
    DWORD  dwDisplayNumColumns;
    DWORD  dwNumRingModes;
    DWORD  dwNumButtonLamps;

    DWORD  dwButtonModesSize;
    DWORD  dwButtonModesOffset;

    DWORD  dwButtonFunctionsSize;
    DWORD  dwButtonFunctionsOffset;
    DWORD  dwLampModesSize;
    DWORD  dwLampModesOffset;

    DWORD  dwNumSetData;
    DWORD  dwSetDataSize;
    DWORD  dwSetDataOffset;

    DWORD  dwNumGetData
    DWORD  dwGetDataSize;
    DWORD  dwGetDataOffset;

    DWORD  dwDevSpecificSize;
    DWORD  dwDevSpecificOffset;

} PHONECAPS, FAR *LPPHONECAPS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold the returned information.
dwUsedSize
The size in bytes of this data structure that contains useful information.
dwProviderInfoSize
dwProviderInfoOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing service-provider specific information. The dwProviderInfoSize/Offset member provides information about the provider hardware or software, such as the vendor name and version numbers of hardware or software. This information can be useful when a user needs to call customer service with problems regarding the provider.
dwPhoneInfoSize
dwPhoneInfoOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device field containing phone-specific information. The dwPhoneInfoSize/Offset member is intended to provide information about the attached phone device, such as the phone-device manufacturer, the model name, the software version, and so on. This information can be useful when a user needs to call customer service with problems regarding the phone.
dwPermanentPhoneID
The permanent DWORD identifier by which the phone device is known in the system's configuration.
dwPhoneNameSize
dwPhoneNameOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device field containing a user-configurable name for this phone device. This name can be configured by the user when configuring the phone device's service provider and is provided for the user's convenience.
dwStringFormat
The string format to be used with this phone device. This member uses the following STRINGFORMAT_ constants:
STRINGFORMAT_ASCII
ASCII string format using one byte per character.
STRINGFORMAT_DBCS
DBCS string format using two bytes per character.
STRINGFORMAT_UNICODE
Unicode string format using two bytes per character.
dwPhoneStates
The state changes for this phone device for which the application can be notified through a PHONE_STATE callback message. This member uses the following PHONESTATE_ constants:
PHONESTATE_OTHER
A phone status information item other than those listed below has changed.
PHONESTATE_CONNECTED
The connection between the phone device and TAPI was just made. This happens when TAPI is first invoked, or when the wire connecting the phone to the computer is plugged in when TAPI is active.
PHONESTATE_DISCONNECTED
The connection between the phone device and TAPI was just broken. This happens when the wire connecting the phone set to the computer is unplugged while TAPI is active.
PHONESTATE_OWNER
The number of owners for the phone device has changed.
PHONESTATE_MONITORS
The number of monitors for the phone device has changed.
PHONESTATE_DISPLAY
The display of the phone has changed.
PHONESTATE_LAMP
A lamp of the phone has changed.
PHONESTATE_RINGMODE
The ring mode of the phone has changed.
PHONESTATE_RINGVOLUME
The ring volume of the phone has changed.
PHONESTATE_HANDSETHOOKSWITCH
The handset hookswitch state has changed.
PHONESTATE_HANDSETVOLUME
The handset's speaker volume setting has changed.
PHONESTATE_HANDSETGAIN
The handset's microphone gain setting has changed.
PHONESTATE_SPEAKERHOOKSWITCH
The speakerphone's hookswitch state has changed.
PHONESTATE_SPEAKERVOLUME
The speakerphone's speaker volume setting has changed.
PHONESTATE_SPEAKERGAIN
The speakerphone's microphone gain setting state has changed.
PHONESTATE_HEADSETHOOKSWITCH
The headset's hookswitch state has changed.
PHONESTATE_HEADSETVOLUME
The headset's speaker volume setting has changed.
PHONESTATE_HEADSETGAIN
The headset's microphone gain setting has changed.
PHONESTATE_SUSPEND
The application's use of the phone is temporarily suspended.
PHONESTATE_RESUME
The application's use of the phone device is resumed after having been suspended for some time.
PHONESTATE_DEVSPECIFIC
The phone's device-specific information has changed.
PHONESTATE_REINIT
Items have changed in the configuration of phone devices. To become aware of these changes (such as of the appearance of new phone devices) the application reinitializes its use of TAPI. If specified, the htPhone parameter is left NULL for this state change as it applies to any of the phones in the system.
dwHookSwitchDevs
The phone's hookswitch devices. This member uses the following PHONEHOOKSWITCHDEV_ constants:
PHONEHOOKSWITCHDEV_HANDSET
The ubiquitous, hand-held ear- and mouthpiece.
PHONEHOOKSWITCHDEV_SPEAKER
A built-in loudspeaker and microphone. This can be an externally connected adjunct to the telephone set.
PHONEHOOKSWITCHDEV_HEADSET
A headset connected to the phone set.
dwHandsetHookSwitchModes
dwSpeakerHookSwitchModes
dwHeadsetHookSwitchModes
Specifies the phone's hookswitch mode capabilities of the handset, speaker, or headset, respectively. These members are only meaningful if the hookswitch device is listed in dwHookSwitchDevs. This member uses the following PHONEHOOKSWITCHMODE_ constants:
PHONEHOOKSWITCHMODE_ONHOOK
The device's microphone and speaker are both onhook.
PHONEHOOKSWITCHMODE_MIC
The device's microphone is active and the speaker is mute.
PHONEHOOKSWITCHMODE_SPEAKER
The device's speaker is active and the microphone is mute.
PHONEHOOKSWITCHMODE_MICSPEAKER
The device's microphone and speaker are both active.
PHONEHOOKSWITCHMODE_UNKNOWN
The device's hookswitch state is unknown or cannot be detected.
dwVolumeFlags
The volume setting capabilities of the phone device's speaker components. If the bit in position PHONEHOOKSWITCHDEV_ is TRUE, the volume of the corresponding hookswitch device's speaker component can be adjusted through TSPI_phoneSetVolume; otherwise, FALSE.
dwGainFlags
The gain setting capabilities of the phone device's microphone components. If the bit position PHONEHOOKSWITCHDEV_ is TRUE, the volume of the corresponding hookswitch device's microphone component can be adjusted using TSPI_phoneSetGain; otherwise, FALSE.
dwDisplayNumRows
The display capabilities of the phone device by describing the number of rows in the phone display. The dwDisplayNumRows and dwDisplayNumColumns members are both zero for a phone device without a display.
dwDisplayNumColumns
The display capabilities of the phone device by describing the number of columns in the phone display. dwDisplayNumRows and dwDisplayNumColumns are both zero for a phone device without a display.
dwNumRingModes
The ring capabilities of the phone device. The phone is able to ring with dwNumRingModes different ring patterns, identified as 1, 2, ... dwNumRingModes minus one. If the value of this member is zero, applications have no control over the ring mode of the phone. If the value of this member is greater than zero, it indicates the number of ring modes in addition to silence that are supported by the service provider. A value of 0 in the lpdwRingMode parameter of TSPI_phoneGetRing or the dwRingMode parameter of TSPI_phoneSetRing indicates silence (the phone is not ringing or should not be rung), and dwRingMode values of 1 to dwNumRingModes are valid ring modes for the phone device.
dwNumButtonLamps
The number of button/lamps on the phone device that are detectable in TAPI. Button/lamps are identified by their identifier. Valid button/lamp identifiers range from zero to dwNumButtonLamps minus one. The keypad buttons '0', through '9', '*', and '#' are assigned the identifiers 0 through 12.
dwButtonModesSize
dwButtonModesOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field containing the button modes of the phone's buttons, of type PHONEBUTTONMODE_. The array is indexed by button/lamp identifier. Values are:
PHONEBUTTONMODE_DUMMY
Used to describe a button/lamp position that has no corresponding button, but has only a lamp. If the phone provides any non-DUMMY buttons, the PHONE_BUTTON message is sent to the application if a button is pressed at the phone device.
PHONEBUTTONMODE_CALL
The button is assigned to a call appearance.
PHONEBUTTONMODE_FEATURE
The button is assigned to requesting features from the switch, such as hold, conference, and transfer.
PHONEBUTTONMODE_KEYPAD
The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'.
PHONEBUTTONMODE_LOCAL
The button is a local function button, such as mute or volume control.
PHONEBUTTONMODE_DISPLAY
The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.
dwButtonFunctionsSize
dwButtonFunctionsOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field containing the button modes of the phone's buttons, of type PHONEBUTTONFUNCTION_. The array is indexed by button/lamp identifier.
dwLampModesSize
dwLampModesOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field containing the lamp modes of the phone's lamps, of type PHONELAMPMODE_. The array is indexed by button/lamp identifier. Values are:
PHONELAMPMODE_BROKENFLUTTER
Broken flutter is the superposition of flash and flutter.
PHONELAMPMODE_FLASH
Flash means slow on and off.
PHONELAMPMODE_FLUTTER
Flutter means fast on and off.
PHONELAMPMODE_OFF
The lamp is off.
PHONELAMPMODE_STEADY
The lamp is continuously lit.
PHONELAMPMODE_WINK
The lamp is winking.
PHONELAMPMODE_DUMMY
This value is used to describe a button/lamp position that has no corresponding lamp.
dwNumSetData
The number of different download areas in the phone device. The different areas are referred to using the data identifiers 0, 1, ..., dwNumSetData minus one. If this member is zero, the phone does not support the download capability.
dwSetDataSize
dwSetDataOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field containing the sizes (in bytes) of the phone's download data areas. This is an array with DWORD-sized elements, indexed by data identifier.
dwNumGetData
The number of different upload areas in the phone device. The different areas are referred to using the data identifiers 0, 1, ..., dwNumGetData minus one. If this member is zero, the phone does not support the upload capability.
dwGetDataSize
dwGetDataOffset
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field containing the sizes (in bytes) of the phone's upload data areas. This is an array with DWORD-sized elements, indexed by data identifier.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device-specific field.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

See Also

PHONEBUTTONMODE_ Constants, PHONEHOOKSWITCHDEV_ Constants, PHONELAMPMODE_ Constants, TSPI_phoneGetDevCaps


PHONEEXTENSIONID

The PHONEEXTENSIONID structure describes an extension identifier. Extension identifiers are used to identify service-provider specific extensions for phone device classes.

typedef struct phoneextensionid_tag {
    DWORD  dwExtensionID0;
   DWORD  dwExtensionID1;
    DWORD  dwExtensionID2;
    DWORD  dwExtensionID3;
} PHONEEXTENSIONID, FAR *LPPHONEEXTENSIONID;

Members

dwExtensionID0
dwExtensionID1
dwExtensionID2
dwExtensionID3
These four DWORD-sized members together specify a universally unique extension identifier that identifies a phone device class extension.

Remarks

Not extensible.

Extension identifiers are generated using an SDK-provided generation utility.

See Also

TSPI_phoneNegotiateTSPIVersion


PHONESTATUS

The PHONESTATUS structure describes the current status of a phone device.

typedef struct phonestatus_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwStatusFlags;
    DWORD  dwNumOwners;
    DWORD  dwNumMonitors;
    DWORD  dwRingMode;
    DWORD  dwRingVolume;

    DWORD  dwHandsetHookSwitchMode;
    DWORD  dwHandsetVolume;
    DWORD  dwHandsetGain;

    DWORD  dwSpeakerHookSwitchMode;
    DWORD  dwSpeakerVolume;
    DWORD  dwSpeakerGain;

    DWORD  dwHeadsetHookSwitchMode;
    DWORD  dwHeadsetVolume;
    DWORD  dwHeadsetGain;

    DWORD  dwDisplaySize;
    DWORD  dwDisplayOffset;

    DWORD  dwLampModesSize;
    DWORD  dwLampModesOffset;

    DWORD  dwOwnerNameSize;
    DWORD  dwOwnerNameOffset;

    DWORD  dwDevSpecificSize;
    DWORD  dwDevSpecificOffset;
} PHONESTATUS, FAR *LPPHONESTATUS;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwStatusFlags
A collection of status flags for this phone device. This member uses the following PHONESTATUSFLAGS_ constants:
PHONESTATUSFLAGS_CONNECTED
Specifies whether the phone is currently connected to TAPI. If connected, TRUE; otherwise, FALSE.
PHONESTATUSFLAGS_SUSPENDED
Specify whether TAPI's manipulation of the phone device is suspended. If suspended, TRUE; otherwise, FALSE. An application's use of a phone device can be temporarily suspended when the switch wants to manipulate the phone in a way that cannot tolerate interference from the application.
dwRingMode
The current ring mode of a phone device.
dwRingVolume
The current ring volume of a phone device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum volume).
dwHandsetHookSwitchMode
The current hookswitch mode of the phone's handset. This member uses the following PHONEHOOKSWITCHMODE_ constants:
PHONEHOOKSWITCHMODE_ONHOOK
The device's microphone and speaker are both onhook.
PHONEHOOKSWITCHMODE_MIC
The devicers microphone is active, the speaker is mute.
PHONEHOOKSWITCHMODE_SPEAKER
The device's speaker is active, the microphone is mute.
PHONEHOOKSWITCHMODE_MICSPEAKER
The device's microphone and speaker are both active.
PHONEHOOKSWITCHMODE_UNKNOWN
The device's hookswitch state is unknown or cannot be detected.
dwHandsetVolume
The current speaker volume of the phone's handset device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum volume).
dwHandsetGain
The current microphone gain of the phone's handset device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum gain).
dwSpeakerHookSwitchMode
The current hookswitch mode of the phone's speakerphone. This member uses the following PHONEHOOKSWITCHMODE_ constants:
PHONEHOOKSWITCHMODE_ONHOOK
The device's microphone and speaker are both onhook.
PHONEHOOKSWITCHMODE_MIC
The devicer's microphone is active, the speaker is mute.
PHONEHOOKSWITCHMODE_SPEAKER
The device's speaker is active, the microphone is mute.
PHONEHOOKSWITCHMODE_MICSPEAKER
The device's microphone and speaker are both active.
PHONEHOOKSWITCHMODE_UNKNOWN
The device's hookswitch state is unknown or cannot be detected.
dwSpeakerVolume
The current speaker volume of the phone's speaker device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum volume).
dwSpeakerGain
The current microphone gain of the phone's speaker device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum gain).
dwHeadsetHookSwitchMode
The current hookswitch mode of the phone's headset. This member uses the following PHONEHOOKSWITCHMODE_ constants:
PHONEHOOKSWITCHMODE_ONHOOK
The device's microphone and speaker are both onhook.
PHONEHOOKSWITCHMODE_MIC
The devicer's microphone is active, the speaker is mute.
PHONEHOOKSWITCHMODE_SPEAKER
The device's speaker is active, the microphone is mute.
PHONEHOOKSWITCHMODE_MICSPEAKER
The device's microphone and speaker are both active.
PHONEHOOKSWITCHMODE_UNKNOWN
The device's hookswitch state is unknown or cannot be detected.
dwHeadsetVolume
The current speaker volume of the phone's headset device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum volume).
dwHeadsetGain
The current microphone gain of the phone's headset device. This is a value between 0x00000000 (silence) and 0x0000FFFF (maximum gain).
dwDisplaySize
dwDisplayOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing the phone's current display information.
dwLampModesSize
dwLampModesOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing the phone's current lamp modes.
dwOwnerNameSize
dwOwnerNameOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing the name of the application that is the current owner of the phone device. The name is the application name provided by the application when it invokes phoneInitialize. If no application name is supplied, the application's module name is used instead. If the phone currently has no owner, dwOwnerNameSize is zero.
dwDevSpecificSize
dwDevSpecificOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device-specific field.

Remarks

Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.

See Also

PHONEHOOKSWITCHDEV_ Constants, PHONEHOOKSWITCHMODE_ Constants, PHONELAMPMODE_ Constants, PHONESTATE_ Constants, PHONESTATUSFLAGS_ Constants, TSPI_phoneGetStatus


VARSTRING

The VARSTRING structure is used by both the line device class and the phone device class for returning variably sized strings.

typedef struct varstring_tag {
    DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;

    DWORD  dwStringFormat;
    DWORD  dwStringSize;
    DWORD  dwStringOffset;
} VARSTRING, FAR *LPVARSTRING;

Members

dwTotalSize
The total size in bytes allocated to this data structure.
dwNeededSize
The size in bytes for this data structure that is needed to hold the returned information.
dwUsedSize
The size in bytes of the portion of this data structure that contains useful information.
dwStringFormat
The format of the string. This member uses the following STRINGFORMAT_ constants:
STRINGFORMAT_ASCII
ASCII string format using one byte per character. The actual string is a NULL-terminated ASCII string with the terminating NULL accounted for in the string size. If dwStringFormat is STRINGFORMAT_ASCII, the actual string is a NULL-terminated ASCII string with the terminating NULL accounted for in the string size.
STRINGFORMAT_DBCS
DBCS string format using one or two bytes per character.
STRINGFORMAT_UNICODE
Unicode string format using two bytes per character.
STRINGFORMAT_BINARY
Array of unsigned characters. It can be used for numeric values.
dwStringSize
dwStringOffset
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device field containing the string information.

Remarks

Not extensible.

If the dwStringSize and dwStringOffset members are set in any one of the following ways, the structure contain no string or an empty string:

  • Both the dwStringSize and dwStringOffset members are 0.
  • The dwStringOffset member is nonzero but dwStringSize is 0.
  • The dwStringOffset member is nonzero, dwStringSize is 1, and the byte at the given offset is 0.

See Also

STRINGFORMAT_ Constants


TUISPI Data Structures

Following are the TUISPI data structures their descriptions.


TUISPICREATEDIALOGINSTANCEPARAMS

typedef struct tuispicreatedialoginstanceparams_tag {
    DRV_REQUESTID        dwRequestID;
    HDRVDIALOGINSTANCE   hdDlgInst;
    HTAPIDIALOGINSTANCE  htDlgInst;
    LPCWSTR              lpszUIDLLName;
    LPVOID               lpParams;
    DWORD                dwSize;
} TUISPICREATEDIALOGINSTANCEPARAMS,
    FAR *LP TUISPICREATEDIALOGINSTANCEPARAMS;

Members

dwRequestID
The dwRequestID passed to the service provider as a parameter in the asynchronous TSPI function with which the spontaneous UI is associated. TAPI uses this to identify the application in whose context the UI DLL is to be loaded and the TUISPI_providerGenericDialog function invoked.
hdDlgInst
The service provider's identifier for the association with the instance of the generic dialog box. Because it is possible for multiple instances of the generic dialog box to be open in the same or multiple applications, the service provider must ensure that its handle is unique within the scope of existing instances within the context of the provider.
htDlgInst
TAPI writes into this member its identifier for the association that is created. This member is set to NULL if creating the association failed, in which case it is impossible for the service provider to create a dialog box spontaneously in the context of the target application. The service provider must use this identifier in messages to send data to the UI DLL (LINE_SENDDIALOGINSTANCEDATA).
lpszUIDLLName
Pointer to a NULL-terminated string specifying the fully qualified name of the UI DLL to load in the application context.
lpParams
Pointer to a private parameter block to be conveyed to the UI DLL's TUISPI_providerGenericDialog function. The contents of the parameter block are determined by the service provider and UI DLL. The transfer is unidirectional; the UI DLL is not able to modify the parameter block and return it to the service provider. Generally, this block instructs the UI DLL which dialog box to display, and contains the information to display (if necessary).
dwSize
The size in bytes of the parameter block.


TSPI Messages

This section contains a list of the messages in the Telephony Service Provider Interface (TSPI). These messages are used to notify TAPI of the occurrence of asynchronous events that spontaneously occur within the service provider. The service provider passes these events to TAPI by calling a LINEEVENT or PHONEEVENT callback function, depending on whether the service provider is reporting an event on a line, call, or phone device. The LINEEVENT procedure for reporting events occurring on a line or call is supplied to the service provider at the time the line is opened with the TSPI_lineOpen function. The PHONEEVENT procedure for reporting events occurring on a phone is supplied with the TSPI_phoneOpen function.

These spontaneous events are unsolicited by TAPI in the sense that they are not a direct response to any request. These events contrast with those reporting completion of requests made by TAPI. Such completion events are reported through the ASYNC_COMPLETION callback function.

The parameter profiles for the spontaneous event procedures include parameters that identify the relevant object for which the event is being reported (phone, line, or call). The identification is in the form of an opaque handle whose exact interpretation is not published by TSPI. TAPI internally determines the relationship between these opaque handles and whatever data structures it used to represent the devices.

The parameter profile for spontaneous event procedures also includes a message parameter identifying the type of the message. Each message type has a corresponding definition that determines the handles that are included, along with other parameters and their meanings. There is a very strong correspondence between the messages appearing at the TSPI level and those that appear at the TAPI level. These are the general rules of correspondence:

  • The set of messages is nearly identical. Where messages correspond, the same message name and value is used at the TSPI level.
  • Handles appearing at the TSPI level are the opaque types defined by the TSPI specification. These types (and their interpretation) differ from those at the TAPI level, although they refer to the same class of device. For example, where a TAPI message includes an HLINE handle, the corresponding TSPI message would typically include an HTAPILINE handle.
  • There is no dwCallbackInstance data passed to the callback.
  • The dwParam1, dwParam2, and dwParam3 parameters are usually identical to the corresponding parameters for the TAPI message.
  • Line-oriented and call-oriented messages are passed to a different callback procedure than phone-oriented messages.

For each message, this section lists the following items:

  • The purpose of the message
  • The callback procedure to which this message is passed
  • A description of the message parameters
  • Optional comments about using the message
  • Optional references to other functions, messages, and data structures
  • Optional comments comparing this message to the TAPI interface

Certain messages are used to notify TAPI about a change in an object's status. These messages provide the TAPI opaque object handle and an indication of which status item has changed. TAPI can subsequently call an appropriate "get status" function of the object to obtain the object's full status.

When an event occurs, a message may or may not be sent to TAPI. For some event types, such as status changes, TAPI specifies a set of status changes in which it is interested. The service provider is advised to limit the status-change message events it reports to those included in this set. The service provider is not required to adhere to this limit. In other words, it may report more changes than are strictly necessary. However, it should try to observe the limit for performance reasons.

The LINE_REPLY message is not used at the TSPI level. Completion of an asynchronous request is reported using the ASYNC_COMPLETION callback.

The PHONE_REPLY message is not used at the TSPI level. Completion of an asynchronous request is reported using the ASYNC_COMPLETION callback.


TSPI Line Device Messages

This section describes the line device messages in the Telephony SPI.


LINE_ADDRESSSTATE

The LINE_ADDRESSSTATE message is sent to the LINEEVENT callback function when the status of an address changes on a line that is currently open by TAPI. TAPI can invoke TSPI_lineGetAddressStatus to determine the current status of the address.

LINE_ADDRESSSTATE
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) 0;
dwMsg = (DWORD) LINE_ADDRESSSTATE;
dwParam1 = (DWORD) idAddress;
dwParam2 = (DWORD) AddressState;
dwParam3 = (DWORD) 0;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
Unused.
dwMsg
The value LINE_ADDRESSSTATE.
dwParam1
The address identifier of the address that changed status.
dwParam2
The address state that changed. This parameter can be a combination of the following LINEADDRESSSTATE_constants:
LINEADDRESSSTATE_OTHER
Address-status items other than those listed below have changed. TAPI can check the current address status to determine which items have changed.
LINEADDRESSSTATE_DEVSPECIFIC
The device-specific item of the address status has changed.
LINEADDRESSSTATE_INUSEZERO
The address has changed to idle (it is now in use by zero stations).
LINEADDRESSSTATE_INUSEONE
The address has changed from being idle or from being in use by many bridged stations to being in use by just one station.
LINEADDRESSSTATE_INUSEMANY
The monitored or bridged address has changed from being in use by one station to being in use by more than one station.
LINEADDRESSSTATE_NUMCALLS
The number of calls on the address has changed. This is the result of an event such as a new inbound call, an outbound call on the address, or a call changing its hold status.
LINEADDRESSSTATE_FORWARD
The forwarding status of the address has changed including the number of rings for determining a no-answer condition. The application can check the address status to determine details about the address's current forwarding status.
LINEADDRESSSTATE_TERMINALS
The terminal settings for the address have changed.
LINEADDRESSSTATE_CAPSCHANGE
Due to configuration changes made by the user or other circumstances, one or more of the members in the LINEADDRESSCAPS structure for the address have changed. If a service provider sends a LINE_ADDRESSSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated this or a later API version; applications negotiating an earlier API version receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shut down and reinitialize their connection to TAPI to obtain the updated information.
dwParam3
Unused.

Remarks

This message is sent whenever the line is open by TAPI and an event occurs in which TAPI has expressed an interest. TAPI uses the TSPI_lineSetStatusMessages function to specify the set of status-change events in which it is interested. By default, address status reporting is disabled.

For backward compatibility, older service providers are not expected to generate this value in a LINE_ADDRESSSTATE message. If they do, the message should be handled in the same manner as for newer service providers (as described earlier).

See Also

LINE_LINEDEVSTATE, LINEADDRESSCAPS, LINEADDRESSSTATUS, LINEEVENT, TSPI_lineGetAddressStatus, TSPI_lineSetStatusMessages


LINE_CALLDEVSPECIFIC

The LINE_CALLDEVSPECIFIC message is sent to the LINEEVENT callback function to notify TAPI about device-specific events occurring on a call. The meaning of the message and the interpretation of the dwParam1 through dwParam3 parameters is device specific.

LINE_CALLDEVSPECIFIC
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_CALLDEVSPECIFIC;
dwParam1 = (DWORD) DeviceData1;
dwParam2 = (DWORD) DeviceData2;
dwParam3 = (DWORD) DeviceData3;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_CALLDEVSPECIFIC.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Remarks

The LINE_CALLDEVSPECIFIC message is used by a service provider in conjunction with the TSPI_lineDevSpecific function. Its meaning is device specific.

TAPI sends the LINE_DEVSPECIFIC message to applications in response to receiving this message from a service provider. The htLine and htCall parameters are translated to the appropriate hCall as the hDevice parameter at the TAPI level. The dwParam1, dwParam2, and dwParam3 parameters are passed through unmodified.

There is no directly corresponding message at the TAPI level, although this message is very similar to LINE_DEVSPECIFIC. At the TSPI level, the device-specific messages are split between those reporting events on lines and addresses, and those reporting events on calls.

See Also

LINE_DEVSPECIFIC, LINEEVENT, TSPI_lineDevSpecific


LINE_CALLDEVSPECIFICFEATURE

The LINE_CALLDEVSPECIFICFEATURE message is sent to the LINEEVENT callback function to notify TAPI about device-specific events occurring on a line or address. The meaning of the message and the interpretation of the dwParam1 through dwParam3 parameters is device specific.

LINE_CALLDEVSPECIFICFEATURE
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_CALLDEVSPECIFICFEATURE;
dwParam1 = (DWORD) DeviceData1;
dwParam2 = (DWORD) DeviceData2;
dwParam3 = (DWORD) DeviceData3;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_CALLDEVSPECIFICFEATURE.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Remarks

This message is used by a service provider in conjunction with the TSPI_lineDevSpecificFeature function. Its meaning is device specific.

TAPI sends the LINE_DEVSPECIFICFEATURE message to applications in response to receiving this message from a service provider. The htLine and htCall parameters are translated to the appropriate hCall as the hDevice parameter at the TAPI level. The dwParam1, dwParam2, and dwParam3 parameters are passed through unmodified.

There is no directly corresponding message at the TAPI level, although this message is very similar to LINE_DEVSPECIFICFEATURE. At the TSPI level, the device-specific feature messages are split between those reporting events on lines and addresses, and those reporting events on calls.

See Also

LINE_DEVSPECIFICFEATURE, TSPI_lineDevSpecificFeature


LINE_CALLINFO

The LINE_CALLINFO message is sent to the LINEEVENT callback function when the call information about the specified call has changed. TAPI can invoke lineGetCallInfo to determine the current call information.

LINE_CALLINFO
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_CALLINFO;
dwParam1 = (DWORD) CallInfoState;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_CALLINFO.
dwParam1
Specifies the call information item that has changed. This parameter can be a combination of the following LINECALLINFOSTATE_ constants:
LINECALLINFOSTATE_OTHER
Information items other than those listed below have changed.
LINECALLINFOSTATE_DEVSPECIFIC
The device-specific field of the call-information record.
LINECALLINFOSTATE_BEARERMODE
The bearer mode field of the call-information record.
LINECALLINFOSTATE_RATE
The rate field of the call-information record.
LINECALLINFOSTATE_MEDIAMODE
The media mode field of the call-information record.
LINECALLINFOSTATE_APPSPECIFIC
The application-specific field of the call-information record.
LINECALLINFOSTATE_CALLID
The call ID field of the call-information record.
LINECALLINFOSTATE_RELATEDCALLID
The related call ID field of the call-information record.
LINECALLINFOSTATE_ORIGIN
The origin field of the call-information record.
LINECALLINFOSTATE_REASON
The reason field of the call-information record.
LINECALLINFOSTATE_COMPLETIONID
The completion ID field of the call-information record.
LINECALLINFOSTATE_TRUNK
The trunk field of the call-information record.
LINECALLINFOSTATE_CALLERID
One of the callerID-related fields of the call-information record.
LINECALLINFOSTATE_CALLEDID
One of the calledID-related fields of the call-information record.
LINECALLINFOSTATE_CONNECTEDID
One of the connectedID-related fields of the call-information record.
LINECALLINFOSTATE_REDIRECTIONID
One of the redirectionID-related fields of the call-information record.
LINECALLINFOSTATE_REDIRECTINGID
One of the redirectingID-related fields of the call-information record.
LINECALLINFOSTATE_DISPLAY
The display field of the call-information record.
LINECALLINFOSTATE_USERUSERINFO
The user-user information of the call-information record.
LINECALLINFOSTATE_HIGHLEVELCOMP
The high-level compatibility field of the call-information record.
LINECALLINFOSTATE_LOWLEVELCOMP
The low-level compatibility field of the call-information record.
LINECALLINFOSTATE_CHARGINGINFO
The charging information of the call-information record.
LINECALLINFOSTATE_TERMINAL
The terminal mode information of the call-information record.
LINECALLINFOSTATE_DIALPARAMS
The dial parameters of the call-information record.
LINECALLINFOSTATE_MONITORMODES
One or more of the digit, tone, or media monitoring fields in the call-information record.
dwParam2
Unused.
dwParam3
Unused.

Remarks

This message is sent to TAPI whenever the event occurs and TAPI has the line open. However, no LINE_CALLINFO messages are sent for a call after the call has entered the idle state.

See Also

LINECALLINFOSTATE_ Constants, TSPI_lineGetCallInfo


LINE_CALLSTATE

The LINE_CALLSTATE message is sent to the LINEEVENT callback function whenever the status of the specified call has changed. Several such messages are typically sent during the lifetime of a call. The first such message for an incoming call indicates the offering state. TAPI can use TSPI_lineGetCallStatus to find out more detailed information about the current status of the call.

LINE_CALLSTATE
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_CALLSTATE;
dwParam1 = (DWORD) LineCallState;
dwParam2 = (DWORD) StateData;
dwParam3 = (DWORD) MediaMode;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_CALLSTATE.
dwParam1
The new call state. This parameter can be one of the following LINECALLSTATE_ constants:
LINECALLSTATE_IDLE
The call is idle; no call actually exists.
LINECALLSTATE_OFFERING
The call is being offered to the station, signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user; alerting is done by the switch instructing the line to ring. It does not affect any call states.
LINECALLSTATE_ACCEPTED
The call was offering and has been accepted. Note that in ISDN, the transition to the accepted state implicitly initiates altering to both parties.
LINECALLSTATE_DIALTONE
The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number.
LINECALLSTATE_DIALING
Destination address information (a phone number) is being sent to the switch through the call. Note that the operation TSPI_lineGenerateDigits does not place the line into the dialing state.
LINECALLSTATE_RINGBACK
The call is receiving ringback from the called address. Ringback indicates that the other station has been reached and is being alerted.
LINECALLSTATE_BUSY
The call is receiving a busy tone. Busy tone indicates that the call cannot be completed; either a circuit (trunk) or the remote party's station are in use.
LINECALLSTATE_SPECIALINFO
Special information is sent by the network. Special information is typically sent when the destination cannot be reached.
LINECALLSTATE_CONNECTED
The call has been established, the connection is made. Information is able to flow over the call between the originating address and the destination address.
LINECALLSTATE_PROCEEDING
Dialing has completed and the call is proceeding through the switch or telephone network.
LINECALLSTATE_ONHOLD
The call is on hold by the switch.
LINECALLSTATE_CONFERENCED
The call is currently a member of a multiparty conference call.
LINECALLSTATE_ONHOLDPENDCONF
The call is currently on hold while it is being added to a conference.
LINECALLSTATE_ONHOLDPENDTRANSFER
The call is currently on hold awaiting transfer to another number.
LINECALLSTATE_DISCONNECTED
The remote party has disconnected from the call.
LINECALLSTATE_UNKNOWN
The state of the call is not known. This can be due to limitations of the call progress detection implementation.
dwParam2
Specifies call-state-dependent information.

If dwParam1 is LINECALLSTATE_BUSY, the dwParam2 parameter contains the details about the busy mode, and uses the following LINEBUSYMODE_ constants:

LINEBUSYMODE_STATION
The busy signal indicates that the called party's station is busy. This is usually signaled with a "normal" busy tone.
LINEBUSYMODE_TRUNK
The busy signal indicates that a trunk or circuit is busy. This is usually signaled with a "long" busy tone.
LINEBUSYMODE_UNKNOWN
The busy signal's specific mode is currently unknown, but can become known later.
LINEBUSYMODE_UNAVAIL
The busy signal's specific mode is unavailable and cannot become known.

If dwParam1 is LINECALLSTATE_DIALTONE, the dwParam2 contains the details about the dial tone mode, and uses the following LINEDIALTONEMODE_ constants:

LINEDIALTONEMODE_NORMAL
This is a "normal" dial tone that typically is a continuous tone.
LINEDIALTONEMODE_SPECIAL
This is a special dial tone indicating a certain condition is currently in effect.
LINEDIALTONEMODE_INTERNAL
This an internal dial tone, as within a PBX.
LINEDIALTONEMODE_EXTERNAL
This is an external (public network) dial tone.
LINEDIALTONEMODE_UNKNOWN
The dial tone mode is currently unknown, but can become known later.
LINEDIALTONEMODE_UNAVAIL
The dial tone mode is unavailable and cannot become known.

If dwParam1 is LINECALLSTATE_SPECIALINFO, the dwParam2 parameter contains the details about the special info mode and uses the following LINESPECIALINFO_ constants:

LINESPECIALINFO_NOCIRCUIT
This special information tone precedes a no-circuit or emergency announcement (trunk blockage category).
LINESPECIALINFO_CUSTIRREG
This special information tone precedes a vacant number, AIS, Centrex number change and nonworking station, access code not dialed or dialed in error, or manual intercept operator message (customer irregularity category).
LINESPECIALINFO_REORDER
This special information tone precedes a reorder announcement (equipment irregularity category).
LINESPECIALINFO_UNKNOWN
Specifics about the special information tone are currently unknown but can become known later.
LINESPECIALINFO_UNAVAIL
Specifics about the special information tone are unavailable, and cannot become known.

If dwParam1 is LINECALLSTATE_DISCONNECTED, the dwParam2 parameter contains the details about the disconnect mode, and uses the following LINEDISCONNECTMODE_ constants:

LINEDISCONNECTMODE_NORMAL
This is a "normal" disconnect request by the remote party. The call was terminated normally.
LINEDISCONNECTMODE_UNKNOWN
The reason for the disconnect request is unknown.
LINEDISCONNECTMODE_REJECT
The remote user has rejected the call.
LINEDISCONNECTMODE_PICKUP
The call was picked up from elsewhere.
LINEDISCONNECTMODE_FORWARDED
The call was forwarded by the switch.
LINEDISCONNECTMODE_BUSY
The remote user's station is busy.
LINEDISCONNECTMODE_NOANSWER
The remote user's station does not answer.
LINEDISCONNECTMODE_BADADDRESS
The destination address in invalid.
LINEDISCONNECTMODE_CONGESTION
The network is congested.
LINEDISCONNECTMODE_INCOMPATIBLE
The remote user's station equipment is incompatible for the type of call requested.
LINEDISCONNECTMODE_UNAVAIL
The reason for the disconnect is unavailable and cannot become known later.
LINEDISCONNECTMODE_NODIALTONE
A dial tone was not detected within a service provider-defined timeout, at a point during dialing when one was expected (such as at a "W" in the dialable string). This can also occur without a service provider-defined timeout period or without a value specified in the dwWaitForDialTone member of the LINEDIALPARAMS structure.

If dwParam1 is LINECALLSTATE_CONFERENCED, dwParam2 contains the htCall of the parent call of the conference of which the subject htCall is a member. If the call specified in dwParam2 was not previously considered by TAPI to be a parent conference call, this message causes it to be so treated. The call specified in dwParam2 must already exist; it was most likely previously created by a LINE_NEWCALL message and set to LINECALLSTATE_ONHOLDPENDCONF.

dwParam3
The media mode of the call, as far as it is known. This is a combination of LINEMEDIAMODE_ constants. If the service provider does not know the media mode, it should include the "UNKNOWN" bit together with all media modes currently being monitored for.

Remarks

The LINE_CALLSTATE message (with LINECALLSTATE_OFFERING) should be sent as the next message for an incoming call after LINE_NEWCALL. Other call state changes are reported whenever they occur; the message cannot be disabled.

The LINE_CALLSTATE message also notifies TAPI about the existence and state of outbound calls established as a side effect of other calls (for example, when an active call is put on hold and replaced by a new call in the dialtone state) or manually by the user (for example, on an attached phone device). The call state of such calls reflects the actual state of the call, which is not offering. By examining the call state, TAPI can determine whether the call is an inbound call that needs to be answered.

The corresponding message at the TAPI level is used to inform applications of new incoming calls. This is not the case at the TSPI level; the LINE_NEWCALL message informs TAPI of new incoming calls. The LINE_NEWCALL message must precede this message.

The dwParam3 parameter is used at the TAPI level to inform the recipient of the privilege level it has over the call.

For backward compatibility, older service providers do not pass a valid htCall in dwParam2. TAPI must check the value passed, and ignore it if it is not a valid htCall. If the value is a valid htCall, TAPI also checks the API version in use on the line device, and establishes a conference call internally only if the API version is 1.4 or later (for example, if the API version on the line is later than 1.4, this parameter should be ignored).

See Also

LINE_NEWCALL, LINEBUSYMODE_ Constants, LINECALLSTATE_ Constants, LINECALLSTATUS, LINEDIALTONEMODE_ Constants, LINESPECIALINFO_ Constants, TSPI_lineGetCallStatus


LINE_CLOSE

The LINE_CLOSE message is sent to the LINEEVENT callback function by the service provider to request that TAPI close the specified line device. Once closed, the line device handle or any call handles for calls on the line are no longer valid. The service provider guarantees that all asynchronous requests on the line and all calls on the line have been reported complete by calling ASYNC_COMPLETION for each outstanding request before this message is sent. TAPI must not request any future operations using this line handle or its associated call handles.

LINE_CLOSE
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) 0;
dwMsg = (DWORD) LINE_CLOSE;
dwParam1 = (DWORD) 0;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
Unused.
dwMsg
The value LINE_CLOSE.
dwParam1
Unused.
dwParam2
Unused.
dwParam3
Unused.

Remarks

The LINE_CLOSE message is a request from the service provider to TAPI to close the line. The service provider must not actually close the line until TAPI acknowledges the request by calling the TSPI_lineClose function to direct the service provider to close the line. A service provider can send this message, for example, when taking the line out of service or reconfiguring the service provider. Whether or not the line can be reopened immediately after it is closed is up to the service provider.

A service provider can also request that a line device be closed after the user has modified the configuration of that line or its driver. If the user wants the configuration changes to be effective immediately (as opposed to after the next system restart), and they affect the application's current view of the device (such as a change in device capabilities), a service provider can close the line device.

See Also

ASYNC_COMPLETION, TSPI_lineClose


LINE_CREATE

A service provider sends a LINE_CREATE message to the LINEEVENT callback function when it desires to create a new device. This can occur when a new device is detected by Plug and Play, or dynamically enabled by the user through a provider configuration function. During the LINEEVENT callback procedure, TAPI simply queues this message for later processing. When the message is received from the queue, the TSPI_providerCreateLineDevice function is called in the context of the TAPISRV.EXE process.

LINE_CREATE
htLine = (HTAPILINE) 0;
htCall = (HTAPICALL) 0;
dwMsg = (DWORD) LINE_CREATE;
dwParam1 = (DWORD) hProvider;
dwParam2 = (DWORD) TempDeviceId;
dwParam3 = (DWORD) 0;

Parameters

htLine
Unused.
htCall
Unused.
dwMsg
The value LINE_CREATE.
dwParam1
The service provider handle (hProvider) as received in TSPI_providerEnumDevices.
dwParam2
Contains a temporary device identifier generated by the service provider. TAPI uses this value in a subsequent call to TSPI_providerCreateLineDevice to assist the provider in associating the message and the function call (in the event that multiple devices are being created).
dwParam3
Unused.

Return Values

No return value.

Remarks

Service providers can (and should) continue to make "static" device allocations at startup when TAPI calls TSPI_providerEnumDevices. Creating known devices using this mechanism, instead of always using LINE_CREATE, involves lower overhead for applications (because they don't have to process LINE_CREATE messages, updated device information, and so on). The LINE_CREATE mechanism is intended to be used only if new devices are created while the service provider is active (for example, between TSPI_providerInit and TSPI_providerShutdown).

This message is sent to the LINEEVENT callback entry point in TAPI. The service provider receives a pointer to this callback in the TSPI_providerEnumDevices function and in each TSPI_lineOpen function; the LINE_CREATE message can be sent to the LINEEVENT callback function given to any open line or at startup.

Devices cannot be removed dynamically. If a service provider wants to remove a line from service, it can send a LINE_LINEDEVSTATE (LINEDEVSTATE_OUTOFSERVICE) message. It would then refuse (for example, by returning LINEERR_INVALLINESTATE) to perform any operation with the device until it returns to service or the provider is shut down and restarted (in which case the device could not be declared in TSPI_providerEnumDevices, effectively removing it from the system).

For backward compatibility, older service providers are not expected to send this message. If they do, the message is treated in the same manner as described earlier for new service providers.

See Also

LINE_LINEDEVSTATE, LINEEVENT, TSPI_lineOpen, TSPI_providerCreateLineDevice, TSPI_providerEnumDevices, TSPI_providerInit, TSPI_providerShutdown


LINE_CREATEDIALOGINSTANCE

The LINE_CREATEDIALOGINSTANCE message causes TAPI to create an association between the service provider and an instance of the TUISPI_providerGenericDialog function executing in the context of the application that invoked the asynchronous TSPI function identified by the dwRequestID parameter of the TUISPICREATEDIALOGINSTANCEPARAMS structure pointed to by lpTUISPICreateDialogInstanceParams.

LINE_CREATEDIALOGINSTANCE
htLine = (DWORD) hProvider;
htCall = (DWORD) 0;
dwMsg = LINE_CREATEDIALOGINSTANCE;
dwParam1 = (DWORD) lpTUISPICreateDialogInstanceParams;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

hProvider
The ProviderHandle supplied to the service provider as a parameter to TSPI_providerEnumDevices.
lpTUISPICreateDialogInstanceParams
Pointer to a TUISPICREATEDIALOGINSTANCEPARAMS structure.

See Also

TSPI_providerEnumDevices, TUISPICREATEDIALOGINSTANCEPARAMS


LINE_DEVSPECIFIC

The LINE_DEVSPECIFIC message is sent to the LINEEVENT callback function to notify TAPI about device-specific events occurring on a line or address. The meaning of the message and the interpretation of the dwParam1 through dwParam3 parameters is device specific.

LINE_DEVSPECIFIC
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) 0;
dwMsg = (DWORD) LINE_DEVSPECIFIC;
dwParam1 = (DWORD) DeviceData1;
dwParam2 = (DWORD) DeviceData2;
dwParam3 = (DWORD) DeviceData3;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
Unused.
dwMsg
The value LINE_DEVSPECIFIC.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Remarks

This message is used by a service provider in conjunction with the TSPI_lineDevSpecific function. Its meaning is device specific.

TAPI sends the LINE_DEVSPECIFIC message to applications in response to receiving this message from a service provider. The htLine is translated to the appropriate hLine as the hDevice parameter at the TAPI level. The dwParam1, dwParam2, and dwParam3 parameters are passed through unmodified.

This differs from the corresponding message at the TAPI level in that it is used only to report device-specific events occurring on a line or address. At the TSPI level, the LINE_CALLDEVSPECIFIC message is used to report device-specific events happening on a call.

See Also

LINE_CALLDEVSPECIFIC, LINEEVENT, TSPI_lineDevSpecific


LINE_DEVSPECIFICFEATURE

The LINE_DEVSPECIFICFEATURE message is sent to the LINEEVENT callback function to notify TAPI about device-specific events occurring on a line or address. The meaning of the message and the interpretation of the dwParam1 through dwParam3 parameters is device specific.

LINE_DEVSPECIFICFEATURE
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) 0;
dwMsg = (DWORD) LINE_DEVSPECIFICFEATURE;
dwParam1 = (DWORD) DeviceData1;
dwParam2 = (DWORD) DeviceData2;
dwParam3 = (DWORD) DeviceData3;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
Unused.
dwMsg
The value LINE_DEVSPECIFICFEATURE.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Remarks

This message is used by a service provider in conjunction with the TSPI_lineDevSpecificFeature function. Its meaning is device specific.

TAPI sends the LINE_DEVSPECIFICFEATURE message to applications in response to receiving this message from a service provider. The htLine is translated to the appropriate hLine as the hDevice parameter at the TAPI level. The dwParam1, dwParam2, and dwParam3 parameters are passed through unmodified.

This differs from the corresponding message at the TAPI level in that it is used only to report device-specific feature events occurring on a line or address. At the TSPI level, the LINE_CALLDEVSPECIFICFEATURE message is used to report device-specific feature events happening on a call.

See Also

LINE_CALLDEVSPECIFICFEATURE, TSPI_lineDevSpecificFeature


LINE_GATHERDIGITS

The LINE_GATHERDIGITS message is sent to the LINEEVENT callback function when the current buffered digit gathering request has terminated. This message is not sent when digit gathering is canceled. The digit buffer can be examined after this message has been received. The effect of examining the digit buffer before this message has been received is undefined.

LINE_GATHERDIGITS
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_GATHERDIGITS;
dwParam1 = (DWORD) LineGatherTerminate;
dwParam2 = (DWORD) dwEndToEndID;
dwParam3 = (DWORD) dwTickCount;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_GATHERDIGITS.
dwParam1
Specifies the reason why digit gathering was terminated. This parameter can be one of the following LINEGATHERTERM_ constants:
LINEGATHERTERM_BUFFERFULL
The requested number of digits has been gathered. The buffer is full.
LINEGATHERTERM_TERMDIGIT
One of the termination digits matched a received digit. The matched termination digit is the last digit in the buffer.
LINEGATHERTERM_FIRSTTIMEOUT
The first digit timeout expired. The buffer contains no digits.
LINEGATHERTERM_INTERTIMEOUT
The inter-digit timeout expired. The buffer contains at least one digit.
LINEGATHERTERM_CANCEL
The request was canceled by a subsequent TSPI_lineGatherDigits request, or because the call terminated.
dwParam2
The dwEndToEndID that was specified in the original TSPI_lineGatherDigits request for which this is the final result.
dwParam3
Service providers shall insert into dwParam3 the "tick count" (number of milliseconds since Windows started), obtained from GetTickCount, at which the digit gathering completed.

Remarks

Calling TSPI_lineGatherDigits while digit gathering is in progress cancels the current digit gathering request and starts a new one, but does not result in the service provider sending this message.

The corresponding message at the TAPI level does not include an end-to-end identifier. End-to-end marking is only done at the TSPI level.

See Also

LINEGATHERTERM_ Constants, TSPI_lineGatherDigits


LINE_GENERATE

The LINE_GENERATE message is sent to the LINEEVENT callback function to notify TAPI 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.

LINE_GENERATE
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_GENERATE;
dwParam1 = (DWORD) LineGenerateTerminate;
dwParam2 = (DWORD) dwEndToEndID;
dwParam3 = (DWORD) dwTickCount;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_GENERATE.
dwParam1
Specifies the reason why digit or tone generation was terminated, and can be one of the following LINEGENERATETERM_ constants:
LINEGENERATETERM_DONE
The requested number of digits have been generated, or the requested tones have been generated for the requested duration.
LINEGENERATETERM_CANCEL
The digit or tone generation request was canceled by an intervening call to TSPI_lineGenerateTone or TSPI_lineGenerateDigits, or because the call terminated.
dwParam2
The dwEndToEndID parameter that was specified in the original TSPI_lineGenerateDigits or TSPI_lineGenerateTone request for which this is the final result.
dwParam3
Service providers insert into dwParam3 the "tick count" (number of milliseconds since Windows started), obtained from GetTickCount, at which the digit or tone generation completed.

Remarks

Calling either TSPI_lineGenerateDigits or TSPI_lineGenerateTone while digit or tone generation is in progress cancels the current digit or tone generation request and starts a new request and also results in the service provider sending this message.

The corresponding message at the TAPI level does not include an end-to-end identifier. End-to-end marking is only done at the TSPI level.

See Also

LINEEVENT, LINEGENERATETERM_ Constants, TSPI_lineGenerateDigits, TSPI_lineGenerateTone


LINE_LINEDEVSTATE

The LINE_LINEDEVSTATE message is sent to the LINEEVENT callback function when the state of a line device has changed. TAPI can invoke TSPI_lineGetLineDevStatus to determine the new status of the line.

LINE_LINEDEVSTATE
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) 0;
dwMsg = (DWORD) LINE_LINEDEVSTATE;
dwParam1 = (DWORD) LineDevState;
dwParam2 = (DWORD) DevStateData1;
dwParam3 = (DWORD) DevStateData2;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
Unused.
dwMsg
The value LINE_LINEDEVSTATE.

Specifies the callback instance supplied when opening the line.

dwParam1
Specifies the line device status item that has changed. This parameter can have multiple flags set and uses the following LINEDEVSTATE_ constants:
LINEDEVSTATE_OTHER
Device-status items other than those listed below have changed.
LINEDEVSTATE_RINGING
The switch tells the line to alert the user. This should be sent repeatedly in a LINE_LINEDEVSTATE message, once for each ring cycle. On a POTS device, the service provider can send the message whenever the central office sends ring voltage. On digital devices such as ISDN, the service provider may need to synthesize the repetition of the message if the switch generates only one ring request. Each repetition of the message should show the ring count increasing, so that toll save functions work properly.
LINEDEVSTATE_CONNECTED
The line was previously disconnected and is now connected to the API.
LINEDEVSTATE_DISCONNECTED
This line was previously connected and is now disconnected from the API.
LINEDEVSTATE_MSGWAITON
The "message waiting" indicator is turned on.
LINEDEVSTATE_MSGWAITOFF
The "message waiting" indicator is turned off.
LINEDEVSTATE_INSERVICE
The line is connected to the API. This happens when the API is first activated, or when the line wire is physically plugged in and in service at the switch while the API is active.
LINEDEVSTATE_OUTOFSERVICE
The line is out of service at the switch or physically disconnected. The API cannot be used to operate on the line device.
LINEDEVSTATE_MAINTENANCE
Maintenance is being performed on the line at the switch. The API cannot be used to operate on the line device.
LINEDEVSTATE_NUMCALLS
The number of calls on the line device has changed.
LINEDEVSTATE_NUMCOMPLETIONS
The number of outstanding call completions on the line device has changed.
LINEDEVSTATE_TERMINALS
The terminal settings have changed.
LINEDEVSTATE_ROAMMODE
The roaming state of the line device has changed.
LINEDEVSTATE_BATTERY
The battery level has changed significantly (cellular).
LINEDEVSTATE_SIGNAL
The signal level has changed significantly (cellular).
LINEDEVSTATE_DEVSPECIFIC
The line's device-specific information has changed.
LINEDEVSTATE_REINIT
Items have changed in the configuration of line devices. Except in extreme cases, the service provider should use the normal configuration change notification mechanism as described in the Overviews section instead of this message. Note that when dwParam1 is LINEDEVSTATE_REINIT, htLine is unused, and should be set to NULL.
LINEDEVSTATE_LOCK
The locked status of the line device has changed.
LINEDEVSTATE_CAPSCHANGE
Due to configuration changes made by the user or other circumstances, one or more of the fields in the LINEDEVCAPS structure for the address have changed. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated this or a subsequent API version; applications negotiating an earlier API version receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI to obtain the updated information.
LINEDEVSTATE_CONFIGCHANGE
Indicates that configuration changes have been made to one or more of the media devices associated with the line device. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated this or a later API version; applications negotiating an earlier API version do not receive any notification.
LINEDEVSTATE_COMPLCANCEL
The call completion identified by the completion identifier contained in the dwParam2 parameter of the LINE_LINEDEVSTATE message has been externally cancelled and is no longer considered valid (if that value were to be passed in a subsequent call to lineUncompleteCall, the function would fail with LINEERR_INVALCOMPLETIONID). If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated this or a later API version; applications negotiating an earlier API version do not receive any notification.
LINEDEVSTATE_REMOVED
The device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated this or a subsequent API version; applications negotiating a previous API version do not receive any notification.
dwParam2
The interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING, dwParam2 contains the ring mode with which the switch instructs the line to ring. Valid ring modes are numbers in the range one to dwNumRingModes, where dwNumRingModes is a line device capability.
dwParam3
The interpretation of this parameter depends on the value of dwParam1. If dwParam1 is LINEDEVSTATE_RINGING, dwParam3 contains the ring count for this ring event. The ring count starts at zero.

Remarks

The sending of this message can be controlled through TSPI_lineSetStatusMessages. The service provider must send LINE_LINEDEVSTATE messages for at least the set of status changes selected through that procedure. The service provider can send more than this set, however, it should try to limit its messages to this set for performance reasons. By default all status reporting is disabled.

At the TSPI level, the service provider does not report state changes when the line is opened and closed, since there is only ever one Open outstanding for the device.

For backward compatibility, older service providers would not be expected to generate these values. If they do, TAPI treats them the same as if the service provider were using API version 1.4 or later (as described earlier).

See Also

LINEDEVSTATUS, LINEEVENT, TSPI_lineGetLineDevStatus, TSPI_lineSetStatusMessages


LINE_MONITORDIGITS

The LINE_MONITORDIGITS message is sent to the LINEEVENT callback function whenever a digit is detected while digit monitoring is in progress. The sending of this message is controlled by the TSPI_lineMonitorDigits function.

LINE_MONITORDIGITS
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_MONITORDIGITS;
dwParam1 = (DWORD) chDigit;
dwParam2 = (DWORD) LineDigitMode;
dwParam3 = (DWORD) dwTickCount;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_MONITORDIGITS.
dwParam1
The low-order byte contains the last digit received in ASCII.
dwParam2
Specifies the digit mode that was detected. This parameter can be one of the following LINEDIGITMODE_ constants:
LINEDIGITMODE_PULSE
Detect digits as audible clicks that are the result of rotary pulse sequences. Valid digits for pulse are '0' through '9'.
LINEDIGITMODE_DTMF
Detect digits as DTMF tones. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.
LINEDIGITMODE_DTMFEND
Detect and provide notification of DTMF down edges. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.
dwParam3
Service providers shall insert into dwParam3 the "tick count" (number of milliseconds since Windows started), obtained from GetTickCount, at which the specified digit was detected.

Remarks

This message is sent only when digit monitoring is enabled.

See Also

LINEEVENT, TSPI_lineMonitorDigits


LINE_MONITORMEDIA

The LINE_MONITORMEDIA message is sent to the LINEEVENT callback function whenever a change in the call's media mode is detected and media mode monitoring is enabled. The sending of this message is controlled by the TSPI_lineMonitorMedia function.

LINE_MONITORMEDIA
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_MONITORDIGITS;
dwParam1 = (DWORD) LineMediaMode;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) dwTickCount;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_MONITORMEDIA.
dwParam1
Specifies the new media mode. This parameter can be one of the following LINEMEDIAMODE_ constants:
LINEMEDIAMODE_INTERACTIVEVOICE
The presence of voice energy on the call, and the call is treated as an interactive call with humans on both ends.
LINEMEDIAMODE_AUTOMATEDVOICE
The presence of voice energy on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM
A data modem session on the call.
LINEMEDIAMODE_G3FAX
A group 3 fax is being sent or received over the call.
LINEMEDIAMODE_TDD
A TDD session on the call. TDD stands for Telephony Devices for the Deaf.
LINEMEDIAMODE_G4FAX
A group 4 fax is being sent or received over the call.
LINEMEDIAMODE_DIGITALDATA
Digital data being sent or received over the call.
LINEMEDIAMODE_TELETEX
A teletex session on the call. Teletex is one of the telematic services.
LINEMEDIAMODE_VIDEOTEX
A videotex session on the call. Videotex is one of the telematic services.
LINEMEDIAMODE_TELEX
A telex session on the call. Telex is one of the telematic services.
LINEMEDIAMODE_MIXED
A mixed session on the call. Mixed is one of the telematic services.
LINEMEDIAMODE_ADSI
An ADSI (Analog Display Services Interface) session on the call.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.
dwParam2
Unused.
dwParam3
Service providers insert into dwParam3 the "tick count" (number of milliseconds since Windows started), obtained from GetTickCount, at which the specified media was detected.

Remarks

This message is sent only when media mode monitoring is enabled.

See Also

LINEEVENT, LINEMEDIAMODE_ Constants, TSPI_lineMonitorMedia


LINE_MONITORTONE

The LINE_MONITORTONE message is sent to the LINEEVENT callback function whenever a monitored tone is detected. The sending of this message is controlled by the TSPI_lineMonitorTones function. A single tone detection can result in the service provider sending this message several times in the case where the detected tone matches several tone descriptions in several different tone lists. A tone can "match" several nonidentical tone descriptions, depending on how close they are to one another and the discrimination limits achieved by the service provider. Multiple matches can occur within the same or different tone lists.

LINE_MONITORTONE
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) hCallDevice;
dwMsg = (DWORD) LINE_MONITORTONE;
dwParam1 = (DWORD) dwAppSpecific;
dwParam2 = (DWORD) dwToneListID;
dwParam3 = (DWORD) dwTickCount;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
The TAPI opaque object handle to the call device.
dwMsg
The value LINE_MONITORTONE.
dwParam1
The application-specific member dwAppSpecific of the LINEMONITORTONE structure for the tone that was detected.
dwParam2
The dwToneListID member of the tone list containing a matching tone description.
dwParam3
Service providers insert into dwParam3 the "tick count" (number of milliseconds since Windows started), obtained from GetTickCount, at which the tone was detected.

Remarks

This message is sent once for each tone it matches in each tone list. Because there can be multiple matches both within a single tone list and across multiple tone lists, a single tone detection can result in several messages, indicating the same dwToneListID and several messages with a differing dwToneListID.

The dwParam2 parameter in the corresponding message at the TAPI level is unused. TAPI forwards all tone monitoring requests from all applications to the service provider to be handled concurrently. It assigns a unique dwToneListID to each tone list and uses the dwToneListID added to dwParam2 at the TAPI level to discriminate the resulting messages.

See Also

LINEEVENT, LINEMONITORTONE, TSPI_lineMonitorTones


LINE_NEWCALL

The LINE_NEWCALL message is sent to the LINEEVENT callback function whenever a new call that TAPI has not originated arrives on a line that TAPI has open. This must be the first message sent regarding that call. TAPI writes the htCall opaque handle to the location passed by the service provider as dwParam2. This gives the service provider the htCall value to be used in subsequent messages.

LINE_NEWCALL
htLine = (HTAPILINE) hLineDevice;
htCall = (HTAPICALL) 0;
dwMsg = (DWORD) LINE_NEWCALL;
dwParam1 = (DWORD)(HDRVCALL) hdCall;
dwParam2 = (DWORD)(LPHTAPICALL) &htCall;
dwParam3 = (DWORD) 0;

Parameters

htLine
The TAPI opaque object handle to the line device.
htCall
Unused.
dwMsg
The value LINE_NEWCALL.
dwParam1
The service provider's opaque handle for the call, of type HDRVCALL. TAPI passes this value as the hdCall parameter to identify the call in subsequent procedures it invokes to operate on the call.
dwParam2
A pointer of type LPHTAPICALL pointing to a HTAPICALL. TAPI writes the TAPI opaque handle for the call to the indicated location. The service provider must save this value and pass it as the htCall parameter to identify the call in subsequent events it reports for the call.

This parameter can also acquire a value of NULL (see the following Remarks section).

dwParam3
Unused.

Remarks

The service provider should send the LINE_CALLSTATE message as the next message for this call. The LINE_NEWCALL event is unusual in that it also passes a value back to the service provider.

This function reports any new calls that originate in the service provider (inbound, outbound, initiated at the phone, and so on) for which TAPI and the service provider have not yet exchanged opaque handles. The handles are exchanged so that TAPI and the service provider can subsequently make requests and report events involving the call. Because these new calls are not necessarily inbound, the calls can initially be in any state, not necessarily the offering state. If the service provider starts and discovers that one or more calls are already active on the line, it informs TAPI of them with LINE_NEWCALL messages followed by LINE_CALLSTATE messages indicating the current state. A new outgoing call, initiated on the phone by the user, would be reported with a LINE_NEWCALL message, and the initial LINE_CALLSTATE message would indicate that the call was in DIALTONE state (and then continuing on from there).

If the service provider passes a large number of calls to TAPI in a very short amount of time (during the same interrupt cycle), TAPI can become backlogged in processing those calls. When this happens, TAPI signals to the service provider to wait a short time before sending any more calls. It signals this by writing a value of NULL, instead of a valid HTAPICALL, into the location pointed to by the dwParam2 parameter of LINE_NEWCALL. This indicates that the attempt to process the newly offered call handle was not successful, most likely due to a temporary inability to allocate memory. The service provider can respond by dropping the call or by resending the LINE_NEWCALL message after a scheduling delay (during which time the service provider should yield the processor to allow TAPI to process other pending actions). In any case, no further messages regarding the new call can be passed to TAPI until the handle exchange succeeds. When the location pointed to by dwParam2 acquires a non-NULL value, the service provider knows that this value is a valid HTAPICALL handle to the call.

There is no directly corresponding message at the TAPI level. This message is used at the TSPI level to uniquely and unambiguously introduce a new incoming call to TAPI and retrieve the TAPI opaque identifier for the call.

See Also

LINE_CALLSTATE, LINEEVENT


LINE_REMOVE

The LINE_REMOVE message notifies TAPI that an existing line device has been or is about to be removed from the system.

LINE_REMOVE
htLine = (DWORD) 0;
htCall = (DWORD) 0;
dwMsg = LINE_REMOVE;
dwParam1 = (DWORD) dwDeviceID;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

dwDeviceID
The device that has been removed.

Remarks

A service provider sends a LINE_REMOVE message to TAPI when it desires to disable an existing line device. This can occur when the removal of the device from the system (in a permanent way) is detected by Plug and Play or through a control panel or other user interface. It should not be used when a device is temporarily disconnected, such as if the device is a PCMCIA card that is extracted (use LINEDEVSTATE_DISCONNECTED or _OUTOFSERVICE in this situation).

When the message is received, TAPI closes the line device (if it is not already closed) by calling TSPI_lineClose, and sends LINE_CLOSE to all applications that have the line open; if any calls are active, TSPI_lineCloseCall is called on each of them prior to TSPI_lineClose. After processing the message, TAPI does not call the service provider referencing the removed device's dwDeviceID. TAPI returns LINEERR_NODEVICE to any application that attempts to reference the removed dwDeviceID.

After TSPI_providerShutdown has been called, the service provider can renumber its devices to remove any numbering "gaps" left by the device removal, so that when TSPI_providerEnumDevices is subsequently called, installed devices are contiguously numbered. The service provider should not reuse the dwPermanentLineID that had been assigned to the device, for as long as possible.

The LINE_REMOVE mechanism is intended to be used only if devices are removed while the service provider is active (for example, between TSPI_providerInit and TSPI_providerShutdown).

This message is sent to TAPI's LINEEVENT callback entry point. The service provider receives a pointer to this callback in the TSPI_providerEnumDevices function and in each TSPI_lineOpen function; the LINE_REMOVE message can be sent to the LINEEVENT callback function given to any open line or at startup.

Backward Compatibility

Older service providers are not expected to send this message. If they do, the message is treated in the same manner as described earlier for new service providers.

See Also

LINE_CLOSE, TSPI_lineClose, TSPI_lineCloseCall, TSPI_lineOpen, TSPI_providerEnumDevices, TSPI_providerInit, TSPI_providerShutdown


LINE_SENDDIALOGINSTANCEDATA

The LINE_SENDDIALOGINSTANCEDATA message causes TAPI to call the TUISPI_providerGenericDialogData function in the UI DLL associated with htDlgInst, passing it the parameter block pointed to by lpParams, of length dwSize.

LINE_SENDDIALOGINSTANCEDATA
htLine = (DWORD) htDlgInst;
htCall = (DWORD) 0;
dwMsg = LINE_SENDDIALOGINSTANCEDATA;
dwParam1 = (DWORD) lpParams;
dwParam2 = (DWORD) dwSize;
dwParam3 = (DWORD) 0;

Parameters

htDlgInst
The HTAPIDIALOGINSTANCE that was returned to the service provider when the dialog box instance was created using LINE_CREATEDIALOGINSTANCE.
lpParams
Pointer to a provider-specific parameter block that is conveyed to the UI DLL TUISPI_providerGenericDialogData function, the size of which is specified by dwSize. If this parameter is set to NULL, this is a request to close the dialog box immediately and clean up (the UI DLL should not invoke TUISPIDLLCALLBACK during this cleanup).
dwSize
The size in bytes of the parameter block to be conveyed to the UI DLL.


TSPI Phone Device Messages

This section describes the phone device messages in the Telephony SPI.


PHONE_BUTTON

The PHONE_BUTTON message is sent to the PHONEEVENT callback function to notify TAPI that it has detected a button press on a phone device that TAPI has open and for which button press monitoring is enabled.

PHONE_BUTTON
htPhone = (HTAPIPHONE) hPhoneDevice;
dwMsg = (DWORD) PHONE_BUTTON;
dwParam1 = (DWORD) idButtonLamp;
dwParam2 = (DWORD) PhoneButtonMode;
dwParam3 = (DWORD) PhoneButtonState;

Parameters

htPhone
The TAPI opaque object handle to the phone device.
dwMsg
The value PHONE_BUTTON.
dwParam1
The button/lamp identifier of the button that was pressed. Note that the button identifiers 0 through 11 are always the KEYPAD buttons. '0' is button identifier 0, '1' is button identifier 1, and so on, through button identifier 9. '*' is button identifier 10, and '#' is button identifier 11. Additional information about a button identifier is available through TSPI_phoneGetDevCaps and TSPI_phoneGetButtonInfo.
dwParam2
The button mode of the button. This parameter uses the following PHONEBUTTONMODE_ constants:
PHONEBUTTONMODE_CALL
The button is assigned to a call appearance.
PHONEBUTTONMODE_FEATURE
The button is assigned to requesting features from the switch, such as hold, conference, or transfer.
PHONEBUTTONMODE_KEYPAD
The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'.
PHONEBUTTONMODE_LOCAL
The button is a local function button, such as mute or volume control.
PHONEBUTTONMODE_DISPLAY
The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.
dwParam3
Specifies whether this is a button down event or a button up event. This parameter uses the following PHONEBUTTONSTATE_ constants:
PHONEBUTTONSTATE_UP
The button is in the "up" state.
PHONEBUTTONSTATE_DOWN
The button is in the "down" state (pressed down).

Remarks

The set of phone button events that is reported is selected by the TSPI_phoneSetStatusMessages function. The service provider must send PHONE_BUTTON messages for at least the set of button press events selected through that procedure. The service provider can send more than this set but should limit its messages to this set for performance reasons.

A PHONE_BUTTON message is sent whenever a button changes state. The service provider must guarantee that each button DOWN event is strictly paired with a button UP event, in that order. Note that a service provider that can detect only one of the button press or release events should expand the event it does detect into a button DOWN message followed by a button UP message.

See Also

PHONEBUTTONFUNCTION_ Constants, PHONEBUTTONMODE_ Constants, PHONEBUTTONSTATE_ Constants, PHONEEVENT, PHONESTATUS, TSPI_phoneGetButtonInfo, TSPI_phoneGetDevCaps, TSPI_phoneSetStatusMessages,


PHONE_CLOSE

The PHONE_CLOSE message is sent to the PHONEEVENT callback function when an open phone device has been forcibly closed. The phone device handle is no longer valid once this message has been sent. The service provider guarantees that all asynchronous requests on the phone have been reported complete by calling ASYNC_COMPLETION for each outstanding request before this message is sent. TAPI must not request any future operations using this phone handle.

PHONE_CLOSE
htPhone = (HTAPIPHONE) hPhoneDevice;
dwMsg = (DWORD) PHONE_CLOSE;
dwParam1 = (DWORD) 0;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

htPhone
The TAPI opaque object handle to the phone device.
dwMsg
The value PHONE_CLOSE.
dwParam1
Unused.
dwParam2
Unused.
dwParam3
Unused.

Remarks

This message is only sent to TAPI after an open phone has been forcibly closed. This can be done, for example, when taking the phone out of service or reconfiguring the service provider. Whether or not the phone can be reopened immediately after a forced close is up to the service provider.

An open phone device can be forcibly closed after the user has modified the configuration of that phone or its driver. If the user wants the configuration changes to be effective immediately (instead of after the next system restart), and they affect the application's current view of the device (such as a change in device capabilities), a service provider can forcibly close the phone device.

See Also

ASYNC_COMPLETION, PHONEEVENT, TSPI_phoneClose


PHONE_CREATE

A service provider sends a PHONE_CREATE message to the PHONEEVENT callback function to create a new device. This can occur when a new device is detected by Plug and Play, or when a new device is dynamically enabled by the user through a provider configuration function. During the PHONEEVENT callback procedure, TAPI simply queues this message for later processing. When the message is received from the queue, the TSPI_providerCreatePhoneDevice function is called in the context of the TAPISRV.EXE process.

PHONE_CREATE
htPhone = (HTAPIPHONE) 0;
dwMsg = (DWORD) PHONE_CREATE;
dwParam1 = (DWORD) hProvider;
dwParam2 = (DWORD) TempDeviceId;
dwParam3 = (DWORD) 0;

Parameters

htPhone
Unused.
dwMsg
The value PHONE_CREATE.
dwParam1
The service provider handle (hProvider) as received in TSPI_providerInit.
dwParam2
Contains a temporary device identifier generated by the service provider. TAPI uses this value in a subsequent call to TSPI_providerCreatePhoneDevice to assist the provider in associating the message and the function call (in the event that multiple devices are being created).
dwParam3
Unused.

Return Values

No return value.

Remarks

Service providers can (and should) continue to make static device allocations at startup when TAPI calls TSPI_providerEnumDevices. Creating known devices using this mechanism, instead of always using PHONE_CREATE, involves lower overhead for applications (because they don't have to process PHONE_CREATE messages, updated device information, and so on). The PHONE_CREATE mechanism is intended to be used only if new devices are created while the service provider is active (for example, between TSPI_providerInit and TSPI_providerShutdown).

This message is sent to the PHONEEVENT callback entry point in TAPI. The service provider receives a pointer to this callback in the TSPI_providerEnumDevices function and in each TSPI_phoneOpen function; the PHONE_CREATE message can be sent to the PHONEEVENT callback function given to any open phone or at startup.

Devices cannot be removed dynamically. If a service provider wants to remove a phone from service, it sends a PHONE_STATE (PHONESTATE_DISCONNECTED) message. It can then refuse (for example, by returning PHONEERR_INVALPHONESTATE) to perform any operation with the device until it returns to service or the provider is shut down and restarted (in which case the device could be not declared in TSPI_providerEnumDevices, effectively removing it from the system).

For backward compatibility, older service providers are not expected to send this message. If they do, the message is treated in the same manner as described above for new service providers.

See Also

PHONEEVENT, TSPI_phoneOpen, TSPI_providerCreatePhoneDevice, TSPI_providerEnumDevices, TSPI_providerInit, TSPI_providerShutdown


PHONE_DEVSPECIFIC

The PHONE_DEVSPECIFIC message is sent to the PHONEEVENT callback function to notify TAPI about device-specific events occurring at the phone. The meaning of the message and the interpretation of the parameters is implementation defined.

PHONE_DEVSPECIFIC
htPhone = (HTAPIPHONE) hPhoneDevice;
dwMsg = (DWORD) PHONE_DEVSPECIFIC;
dwParam1 = (DWORD) DeviceData1;
dwParam2 = (DWORD) DeviceData2;
dwParam3 = (DWORD) DeviceData3;

Parameters

htPhone
The TAPI opaque object handle to the phone device.
dwMsg
The value PHONE_DEVSPECIFIC.
dwParam1
Device specific.
dwParam2
Device specific.
dwParam3
Device specific.

Remarks

TAPI sends the PHONE_DEVSPECIFIC message to applications in response to receiving this message from a service provider. The htPhone is translated to the appropriate hPhone as the hDevice parameter at the TAPI level. The dwParam1, dwParam2, and dwParam3 parameters are passed through unmodified.

See Also

PHONEEVENT, TSPI_phoneDevSpecific


PHONE_REMOVE

The PHONE_REMOVE message notifies TAPI that a phone device has been or is about to be removed from the system.

PHONE_REMOVE
htPhone = (DWORD) 0;
dwMsg = PHONE_REMOVE;
dwParam1 = (DWORD) dwDeviceID;
dwParam2 = (DWORD) 0;
dwParam3 = (DWORD) 0;

Parameters

dwDeviceID
The device that has been removed.

Remarks

A service provider sends a PHONE_REMOVE message to TAPI to disable an existing phone device. This can occur when the removal of the device from the system (in a permanent way) is detected by Plug and Play or through a control panel or other user interface. It should not be used when a device is temporarily disconnected, such as if the device is a PCMCIA card that is extracted (use PHONESTATE_DISCONNECTED in this situation).

When the message is received, TAPI closes the phone device (if it is not already closed) by calling TSPI_phoneClose, and sends PHONE_CLOSE to all applications that have the phone open. After processing the message, TAPI does not call the service provider referencing the removed device's dwDeviceID. TAPI returns PHONEERR_NODEVICE to any application that attempts to reference the removed dwDeviceID.

After TSPI_providerShutdown has been called, the service provider can renumber its devices to remove any numbering "gaps" left by the device removal, so that when TSPI_providerEnumDevices is subsequently called, installed devices are contiguously numbered. The service provider should not reuse the dwPermanentPhoneID that had been assigned to the device, for as long as possible.

The PHONE_REMOVE mechanism is to be used only if devices are removed while the service provider is active (for example, between TSPI_providerInit and TSPI_providerShutdown).

This message is sent to the PHONEEVENT callback entry point in TAPI. The service provider receives a pointer to this callback in the TSPI_providerEnumDevices function and in each TSPI_phoneOpen function; the PHONE_REMOVE message can be sent to the PHONEEVENT callback function given to any open phone or at startup.

Backward Compatibility

Older service providers are not expected to send this message. If they do, the message is treated in the same manner as described above for new service providers.

See Also

PHONE_CLOSE, PHONEEVENT, TSPI_phoneClose, TSPI_phoneOpen, TSPI_providerInit, TSPI_providerShutdown


PHONE_STATE

The PHONE_STATE message is sent to the PHONEEVENT callback function to TAPI whenever a phone device's status changes.

PHONE_STATE
htPhone = (HTAPIPHONE) hPhoneDevice;
dwMsg = (DWORD) PHONE_STATE;
dwParam1 = (DWORD) PhoneState;
dwParam2 = (DWORD) PhoneStateData;
dwParam3 = (DWORD) 0;

Parameters

htPhone
The TAPI opaque object handle to the phone device.
dwMsg
The value PHONE_STATE.
dwParam1
The phone state that has changed. This parameter uses the following PHONESTATE_ constants:
PHONESTATE_OTHER
A phone status information item other than those listed below has changed.
PHONESTATE_CONNECTED
The connection between the phone device and TAPI was just made. This happens when TAPI is first invoked, or when the wire connecting the phone to the computer is plugged in with TAPI active.
PHONESTATE_DISCONNECTED
The connection between the phone device and TAPI was just broken. This happens when the wire connecting the phone set to the computer is unplugged while TAPI is active.
PHONESTATE_DISPLAY
The display of the phone has changed.
PHONESTATE_LAMP
A lamp of the phone has changed.
PHONESTATE_RINGMODE
The ring mode of the phone has changed.
PHONESTATE_RINGVOLUME
The ring volume of the phone has changed.
PHONESTATE_HANDSETHOOKSWITCH
The handset hookswitch state has changed.
PHONESTATE_HANDSETVOLUME
The handset's speaker volume setting has changed.
PHONESTATE_HANDSETGAIN
The handset's mic gain setting has changed.
PHONESTATE_SPEAKERHOOKSWITCH
The speakerphone's hookswitch state has changed.
PHONESTATE_SPEAKERVOLUME
The speakerphone's speaker volume setting has changed.
PHONESTATE_SPEAKERGAIN
The speakerphone's mic gain setting state has changed.
PHONESTATE_HEADSETHOOKSWITCH
The headset's hookswitch state has changed.
PHONESTATE_HEADSETVOLUME
The headset's speaker volume setting has changed.
PHONESTATE_HEADSETGAIN
The headset's mic gain setting has changed.
PHONESTATE_SUSPEND
The application's use of the phone is temporarily suspended.
PHONESTATE_RESUME
The application's use of the phone device is resumed after having been suspended for some time.
PHONESTATE_DEVSPECIFIC
The phone's device-specific information has changed.
PHONESTATE_REINIT
Items have changed in the configuration of phone devices. To become aware of these changes (as with the appearance of new phone devices), the application should reinitialize its use of TAPI. If specified, the htPhone parameter is left NULL for this state change as it applies to any of the phones in the system.
PHONESTATE_CAPSCHANGE
Due to configuration changes made by the user or other circumstances, one or more of the members in the PHONECAPS structure have changed. If a service provider sends a PHONE_STATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated this or a later API version; applications negotiating an earlier API version receive PHONE_STATE messages specifying PHONESTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI to obtain the updated information.
dwParam2
Phone-state dependent information detailing the status change. This parameter is not used if multiple flags are set in dwParam1, because multiple status items have changed. TAPI should invoke TSPI_phoneGetStatus to obtain a complete set of information. If dwParam1 is PHONESTATE_LAMP, dwParam2 contains the button/lamp identifier of the lamp that has changed. If dwParam1 is PHONESTATE_RINGMODE, dwParam2 contains the new ring mode. If dwParam1 is PHONESTATE_HANDSETHOOKSWITCH, PHONESTATE_SPEAKERHOOKSWITCH or PHONESTATE_HEADSETHOOKSWITCH, dwParam2 contains the new hookswitch mode of that hookswitch device, which can be set to any of the following PHONEHOOKSWITCHMODE_ constants:
PHONEHOOKSWITCHMODE_ONHOOK
The device's mic and speaker are both onhook.
PHONEHOOKSWITCHMODE_MIC
The device's mic is active, the speaker is mute.
PHONEHOOKSWITCHMODE_SPEAKER
The device's speaker is active, the mic is mute.
PHONEHOOKSWITCHMODE_MICSPEAKER
The device's mic and speaker are both active.
dwParam3
Unused.

Remarks

The sending of this message is controlled by TSPI_phoneSetStatusMessages. By default, this message is disabled for all state changes.

The service provider never reports changed values for PHONESTATE_OWNER or PHONESTATE_MONITORS, because the notion of privilege does not appear at the TSPI level.

For backward compatibility, older service providers are not expected to generate this value in a PHONE_STATE message. If they do, the message is handled in the same manner as for newer service providers (as described earlier).

See Also

PHONEEVENT, PHONEHOOKSWITCHMODE_ Constants, PHONESTATE_ Constants, TSPI_phoneGetStatus, TSPI_phoneSetStatusMessages


TSPI Constants

This section describes the line-device constants defined by the Telephony SPI.


Constant Extensibility

Provisions are made for extending constants and structures both in a device-independent way and in a device-specific (vendor-specific) way.

In constants that are scalar enumerations, a range of values is reserved for future common extensions. The remainder of values is identified as device specific. A vendor can define meanings for these values in any way desired. The interpretation of these values is keyed to the extension ID provided through the LINEDEVCAPS data structure. For constants that are defined as bit flags, a range of low-order bits are reserved, where the high-order bits can be extension specific. It is recommended that extended values and bit arrays use bits from the highest value or high-order bit down. This leaves the option to move the border between the common portion and extension portion if needed to do so in the future. Extensions to data structures are assigned a variably sized field with size/offset being part of the fixed part. TSPI describes what device-specific extensions are allowed for each data structure.

In addition to recognizing a specific extension identifier, TAPI (operating on behalf of an application) must negotiate the extension version number that the application and the service provider will operate under. This is done using the TSPI_lineNegotiateExtVersion and TSPI_phoneNegotiateExtVersion functions.

An extension identifier is a globally unique identifier. There is no central registry for extension identifiers. Instead, they are generated locally by the manufacturer by a utility that is available with the toolkit. To guarantee global uniqueness, the number is composed of parts such as a (unique) LAN address, time of day, and a random number. Globally Unique Identifiers are designed to be distinguishable from HP/DEC universally unique identifiers and are thus fully compatible with them.


TSPI Line Device Constants

This section contains a list of the line device constants in the Telephony SPI.


LINEADDRCAPFLAGS_ Constants

The LINEADDRCAPFLAGS_ bit-flag constants are used in the dwAddrCapFlags member of the LINEADDRESSCAPS data structure to describe various Boolean address capabilities.

LINEADDRCAPFLAGS_FWDNUMRINGS
Specifies whether the number of rings for a no answer can be specified when forwarding calls on no answer. If TRUE, the valid range is provided in LINEADDRESSCAPS.
LINEADDRCAPFLAGS_PICKUPGROUPID
Specifies whether a group identifier is required for call pickup.
LINEADDRCAPFLAGS_SECURE
Specifies whether calls on this address can be made secure at call setup time.
LINEADDRCAPFLAGS_BLOCKIDDEFAULT
Specifies whether the network by default sends or blocks caller ID information when making a call on this address. If TRUE, identifier information is blocked by default; if FALSE, identifier information is transmitted by default.
LINEADDRCAPFLAGS_BLOCKIDOVERRIDE
Specifies whether the default setting for sending or blocking of caller ID information can be overridden per call. If TRUE, override is possible; if FALSE, override is not possible.
LINEADDRCAPFLAGS_DIALED
Specifies whether a destination address can be dialed on this address for making a call. TRUE if a destination address must be dialed; FALSE if the destination address is fixed (such as with a "hot phone").
LINEADDRCAPFLAGS_ORIGOFFHOOK
Specifies whether the originating party's phone can automatically be taken offhook when making calls.
LINEADDRCAPFLAGS_DESTOFFHOOK
Specifies whether the called party's phone can automatically be forced offhook when making calls.
LINEADDRCAPFLAGS_FWDCONSULT
Specifies whether call forwarding involves the establishment of a consultation call.
LINEADDRCAPFLAGS_SETUPCONFNULL
Specifies whether setting up a conference call starts out with an initial call (FALSE) or with no initial call (TRUE).
LINEADDRCAPFLAGS_AUTORECONNECT
Specifies whether dropping a consultation call automatically reconnects to the call on consultation hold. TRUE if reconnect happens automatically, FALSE otherwise.
LINEADDRCAPFLAGS_COMPLETIONID
Specifies whether the completion IDs returned by TSPI_lineCompleteCall are useful and unique. TRUE is useful; FALSE otherwise.
LINEADDRCAPFLAGS_TRANSFERHELD
Specifies whether a (hard) held call can be transferred. Often, only calls on consultation hold may transferred.
LINEADDRCAPFLAGS_TRANSFERMAKE
Specifies whether an entirely new call can be established for use as a consultation call on transfer.
LINEADDRCAPFLAGS_CONFERENCEHELD
Specifies whether a (hard) held call can be conferenced to. Often, only calls on consultation hold can be added to as a conference call.
LINEADDRCAPFLAGS_CONFERENCEMAKE
Specifies whether an entirely new call can be established for use as a consultation call (to add) on conference.
LINEADDRCAPFLAGS_PARTIALDIAL
Specifies whether partial dialing is available.
LINEADDRCAPFLAGS_FWDSTATUSVALID
Specifies whether the forwarding status in the LINEADDRESSSTATUS structure for this address is valid or is at most a best estimate given absence of accurate confirmation by the switch or network.
LINEADDRCAPFLAGS_FWDINTEXTADDR
Specifies whether internal and external calls can be forwarded to different forwarding addresses. This flag is meaningful only if forwarding of internal and external calls can be controlled separately. This flag is TRUE if internal and external calls can be forwarded to different destination addresses; FALSE otherwise.
LINEADDRCAPFLAGS_FWDBUSYNAADDR
Specifies whether call forwarding for busy and no answer can use different forwarding addresses. This flag is meaningful only if forwarding for busy and no answer can be controlled separately. This flag is TRUE if forwarding for busy and no answer can use different destination addresses; FALSE otherwise.
LINEADDRCAPFLAGS_ACCEPTTOALERT
This flag has the value of TRUE if an offering call must be accepted using lineAccept to start alerting the users at both ends of the call; Otherwise, it is FALSE. This flag is typically only used with ISDN.
LINEADDRCAPFLAGS_CONFDROP
This flag has the value of TRUE if lineDrop of a conference call parent also has the side effect of dropping (disconnecting) the other parties involved in the conference call. It is FALSE if dropping a conference call still allows the other parties to talk among themselves.
LINEADDRCAPFLAGS_PICKUPCALLWAIT
This flag has the value of TRUE if linePickup can be used to pick up a call detected by the user as a call waiting call. Otherwise, it is FALSE.

Not extensible. All 32 bits are reserved.

See Also

LINEADDRESSCAPS, LINEADDRESSSTATUS, TSPI_lineCompleteCall


LINEADDRESSMODE_ Constants

The LINEADDRESSMODE_ bit-flag constants describe ways of identifying an address on a line device.

LINEADDRESSMODE_ADDRESSID
The address is specified using a small integer in the range 0 to dwNumAddresses minus one, where dwNumAddresses is the value in the line's device capabilities.
LINEADDRESSMODE_DIALABLEADDR
The address is specified through its phone number.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

This datatype is used to select an address on a line on which to originate a call. The usual model would select the address by means of its address identifier. Address identifiers are the mechanism used to identify addresses throughout TAPI. However, when making a call in some environments, it is often more practical to identify a call's originating address by phone number rather than by address identifier. One example is in the possible modeling of large numbers of stations (third-party) on the switch by means of one line device with many addresses. The line represents the set of all stations, and each station is mapped to an address with its own primary phone number and address identifier.

See Also

LINECALLPARAMS, LINEDEVCAPS, TSPI_lineGetAddressCaps, TSPI_lineGetAddressID, TSPI_lineMakeCall


LINEADDRESSSHARING_ Constants

The LINEADDRESSSHARING_ bit-flag constants describe ways an address can be shared between lines.

LINEADDRESSSHARING_PRIVATE
The address is private to the user's line, and is not assigned to any other station.
LINEADDRESSSHARING_BRIDGEDEXCL
The address is bridged to one or more other stations. The first line to activate a call on the line has exclusive access to the address and calls that can exist on it. Other lines cannot use the bridged address while it is in use.
LINEADDRESSSHARING_BRIDGEDNEW
The address is bridged with one or more other stations. The first line to activate a call on the line has exclusive access to only the corresponding call. Other applications that use the address result in new and separate call appearances.
LINEADDRESSSHARING_BRIDGEDSHARED
The address is bridged with one or more other lines. All bridged parties can share in calls on the address, which then functions as a conference.
LINEADDRESSSHARING_MONITORED
This is an address whose idle/busy status is made available to this line.

Not extensible. All 32 bits are reserved.

The way in which an address is shared across lines can affect the behavior of that address. LINE_CALLSTATE and LINE_ADDRESSSTATE messages are sent to the application in response to activities by the bridging stations. An application can track the status of the address in these messages.

See Also

LINE_ADDRESSSTATE, LINE_CALLSTATE, LINEADDRESSCAPS


LINEADDRESSSTATE_ Constants

The LINEADDRESSSTATE_ bit-flag constants describe various address status items.

LINEADDRESSSTATE_OTHER
Address-status items other than those listed below have changed.
LINEADDRESSSTATE_DEVSPECIFIC
The device-specific item of the address status has changed.
LINEADDRESSSTATE_INUSEZERO
The address has changed to idle (it is not in use by any stations).
LINEADDRESSSTATE_INUSEONE
The address has changed from being idle or from being in use by many bridged stations to being in use by just one station.
LINEADDRESSSTATE_INUSEMANY
The monitored or bridged address has changed from being in use by one station to being in use by more than one station.
LINEADDRESSSTATE_NUMCALLS
The number of calls on the address has changed. This is the result of such things as a new inbound call, an outbound call on the address, or a call changing its hold status. If this bit is set, one or more of the following members in the LINEADDRESSSTATUS structure has changed: dwNumActiveCalls, dwNumOnHoldCalls, and dwNumOnHoldPendingCalls. The application should check all three members when it receives a LINE_ADDRESSSTATE (numCalls) message.
LINEADDRESSSTATE_FORWARD
The forwarding status of the address has changed, including possibly the number of rings for determining a no-answer condition. The application should check the address status to determine details about the address's current forwarding status.
LINEADDRESSSTATE_TERMINALS
The terminal settings for the address have changed.

Not extensible. All 32 bits are reserved.

An application is notified about changes to these status items in the LINE_ADDRESSSTATE message. The address's device capabilities indicate which address state changes can possibly be reported for this address.

See Also

LINE_ADDRESSSTATE, LINEADDRESSCAPS


LINEADDRFEATURE_ Constants

The LINEADDRFEATURE_ constants list the operations that can be invoked on an address using this API.

LINEADDRFEATURE_FORWARD
The address can be forwarded.
LINEADDRFEATURE_MAKECALL
An outbound call can be placed on the address.
LINEADDRFEATURE_PICKUP
A call can be picked up at the address.
LINEADDRFEATURE_SETMEDIACONTROL
Media control can be set on this address.
LINEADDRFEATURE_SETTERMINAL
The terminal modes for this address can be set.
LINEADDRFEATURE_SETUPCONF
A conference call with a NULL initial call can be set up at this address.
LINEADDRFEATURE_UNCOMPLETECALL
Call completion requests can be canceled at this address.
LINEADDRFEATURE_UNPARK
Calls can be unparked using this address.

Not extensible. All 32 bits are reserved.

This datatype is used both in LINEADDRESSCAPS (returned by TSPI_lineGetAddressCaps) and in LINEADDRESSSTATUS (returned by TSPI_lineGetAddressStatus). LINEADDRESSCAPS reports the availability of the address features by the service provider (mainly the switch) for a given address. An application would make this determination when it initializes. LINEADDRESSSTATUS reports, for a given address, the address features that can actually be invoked while the address is in the current state. An application can make this determination dynamically, after address state changes that are typically caused by call-related activities on the address.

See Also

LINEADDRESSCAPS, LINEADDRESSSTATUS, TSPI_lineGetAddressCaps, TSPI_lineGetAddressStatus


LINEANSWERMODE_ Constants

The LINEANSWERMODE_ bit-flag constants describe how an existing active call on a line device is affected by answering another offering call on the same line.

LINEANSWERMODE_NONE
Answering another call on the same line has no effect on the existing active call(s) on the line.
LINEANSWERMODE_DROP
The currently active call is automatically dropped.
LINEANSWERMODE_HOLD
The currently active call is automatically placed on hold.

Not extensible. All 32 bits are reserved.

If a call comes in (is offered) at the time another call is already active, the new call is connected to by invoking TSPI_lineAnswer. The effect this has on the existing active call depends on the line's device capabilities. The first call may be unaffected, automatically dropped, or automatically placed on hold.

See Also

LINEDEVCAPS


LINEBEARERMODE_ Constants

The LINEBEARERMODE_ bit-flag constants describe different bearer modes of a call. When an application makes a call, it can request a specific bearer mode. These modes are used to select a certain quality of service for the requested connection from the underlying telephone network. Bearer modes available on a given line are a device capability of the line.

LINEBEARERMODE_VOICE
A regular 3.1kHz analog voice grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.
LINEBEARERMODE_SPEECH
Corresponds to G.711 speech transmission on the call. The network can use processing techniques such as analog transmission, echo cancellation and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.
LINEBEARERMODE_MULTIUSE
The multiuse mode defined by ISDN.
LINEBEARERMODE_DATA
The unrestricted data transfer on the call. The data rate is specified separately.
LINEBEARERMODE_ALTSPEECHDATA
The alternate transfer of speech or unrestricted data on the same call (ISDN).
LINEBEARERMODE_NONCALLSIGNALING
A non-call-associated signaling connection from the application to the service provider or switch (treated as a "media stream" by the Telephony API).
LINEBEARERMODE_PASSTHROUGH
When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 comm functions, for the purpose of configuring or using special features not otherwise supported by the service provider.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Note that bearer mode and media mode are different notions. The bearer mode of a call is an indication of the quality of the telephone connection as provided primarily by the network. The media mode of a call is an indication of the type of information stream that is exchanged over that call. Group 3 fax or data modem are media modes that use a call with a 3.1kHz voice bearer mode.

See Also

LINECALLINFO, LINECALLPARAMS


LINEBUSYMODE_ Constants

The LINEBUSYMODE_ bit-flag constants describe different busy signals that the switch or network can generate. The different busy signals typically indicate that a different resource required to make a call is currently in use.

LINEBUSYMODE_STATION
The busy signal indicates that the called party's station is busy. This is usually signaled with a "normal" busy tone.
LINEBUSYMODE_TRUNK
The busy signal indicates that a trunk or circuit is busy. This is usually signaled with a "fast" busy tone.
LINEBUSYMODE_UNKNOWN
The busy signal's specific mode is currently unknown, but can become known later.
LINEBUSYMODE_UNAVAIL
The busy signal's specific mode is unavailable and cannot become known.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Note that busy signals may be sent as inband tones or out-of-band messages. TAPI makes no assumption about the specific signaling mechanism.

See Also

LINECALLSTATUS


LINECALLCOMPLCOND_ Constants

The LINECALLCOMPLCOND_ bit-flag constants describe different ways in which a call can be completed.

LINECALLCOMPLCOND_BUSY
Completion of the call under busy conditions.
LINECALLCOMPLCOND_NOANSWER
Completion of the call under ringback no answer conditions.

Not extensible. All 32 bits are reserved.

See Also

LINEADDRESSCAPS, TSPI_lineCompleteCall


LINECALLCOMPLMODE_ Constants

The LINECALLCOMPLMODE_ bit-flag constants describe different ways in which a call can be completed.

LINECALLCOMPLMODE_CAMPON
Queue the call until the call can be completed.
LINECALLCOMPLMODE_CALLBACK
Request the called station to return the call when it returns to idle.
LINECALLCOMPLMODE_INTRUDE
Add the application to the existing call at the called station (barge in).
LINECALLCOMPLMODE_MESSAGE
Leave a short predefined message for the called station (Leave Word Calling). The message to be sent is specified separately.

Not extensible. All 32 bits are reserved.

See Also

LINEADDRESSCAPS, TSPI_lineCompleteCall


LINECALLFEATURE_ Constants

The LINECALLFEATURE_ constants list the operations that can be invoked on a call using this API.

Not extensible. All 32 bits are reserved.

These constants are used both in LINEADDRESSCAPS (returned by TSPI_lineGetAddressCaps) and in LINECALLSTATUS (returned by TSPI_lineGetCallStatus). LINEADDRESSCAPS reports the general availability of the call features on the specified address. An application can use this information when it initializes in order to determine what it can do later when calls actually do exist. LINECALLSTATUS reports for the specified call the call features that can actually be invoked while the call is in the current call state. The latter takes call privileges into account. An application makes this determination dynamically, after call state changes.

See Also

LINE_CALLSTATE, LINEADDRESSCAPS, LINECALLSTATUS, TSPI_lineGetAddressCaps, TSPI_lineGetCallStatus


LINECALLINFOSTATE_ Constants

The LINECALLINFOSTATE_ bit-flag constants describe various call information items about which an application can be notified in the LINE_CALLINFO message.

LINECALLINFOSTATE_OTHER
Call information-status items other than those listed below have changed.
LINECALLINFOSTATE_DEVSPECIFIC
The device-specific field of the call-information record.
LINECALLINFOSTATE_BEARERMODE
The bearer mode field of the call-information record.
LINECALLINFOSTATE_RATE
The rate field of the call-information record.
LINECALLINFOSTATE_MEDIAMODE
The media mode field of the call-information record.
LINECALLINFOSTATE_APPSPECIFIC
The application-specific field of the call-information record.
LINECALLINFOSTATE_CALLID
The call ID field of the call-information record.
LINECALLINFOSTATE_RELATEDCALLID
The related call ID field of the call-information record.
LINECALLINFOSTATE_ORIGIN
The origin field of the call-information record.
LINECALLINFOSTATE_REASON
The reason field of the call-information record.
LINECALLINFOSTATE_COMPLETIONID
The completion ID field of the call-information record.
LINECALLINFOSTATE_NUMOWNERINCR
The number of owner field in the call-information record was increased.
LINECALLINFOSTATE_NUMOWNERDECR
The number of owner field in the call-information record was decreased.
LINECALLINFOSTATE_NUMMONITORS
The number of monitors field in the call-information record has changed.
LINECALLINFOSTATE_TRUNK
The trunk field of the call-information record.
LINECALLINFOSTATE_CALLERID
One of the callerID-related fields of the call-information record.
LINECALLINFOSTATE_CALLEDID
One of the calledID-related fields of the call-information record.
LINECALLINFOSTATE_CONNECTEDID
One of the connectedID-related fields of the call-information record.
LINECALLINFOSTATE_REDIRECTIONID
One of the redirectionID-related fields of the call-information record.
LINECALLINFOSTATE_REDIRECTINGID
One of the redirectingID-related fields of the call-information record.
LINECALLINFOSTATE_DISPLAY
The display field of the call-information record.
LINECALLINFOSTATE_USERUSERINFO
The user-to-user information of the call-information record.
LINECALLINFOSTATE_HIGHLEVELCOMP
The high-level compatibility field of the call-information record.
LINECALLINFOSTATE_LOWLEVELCOMP
The low-level compatibility field of the call-information record.
LINECALLINFOSTATE_CHARGINGINFO
The charging information of the call-information record.
LINECALLINFOSTATE_TERMINAL
The terminal mode information of the call-information record.
LINECALLINFOSTATE_DIALPARAMS
The dial parameters of the call-information record.
LINECALLINFOSTATE_MONITORMODES
One or more of the digit, tone, or media monitoring fields in the call-information record.

Not extensible. All 32 bits are reserved.

These constants describe portions of the LINECALLINFO data structure. When changes occur in this data structure, a LINE_CALLINFO message is sent to the application. The parameters to this message are a handle to the call and an indication of the information item that has changed.

The LINEADDRESSCAPS data structure also indicates which of these call information elements are every valid for calls on the address.

See Also

LINE_CALLINFO, LINEADDRESSCAPS, LINECALLINFO


LINECALLORIGIN_ Constants

The LINECALLORIGIN_ constants describe the origin of a call.

LINECALLORIGIN_INBOUND
The call originated as an inbound call.
LINECALLORIGIN_OUTBOUND
The call originated from this station as an outbound call.
LINECALLORIGIN_INTERNAL
The call originated as an inbound call at a station internal to the same switching environment.
LINECALLORIGIN_EXTERNAL
The call originated as an inbound call on an external line.
LINECALLORIGIN_UNKNOWN
The call is an inbound call, but its origin is currently unknown but may become known later.
LINECALLORIGIN_UNAVAIL
The call is an inbound call, and its origin is not available and cannot become known for this call.
LINECALLORIGIN_CONFERENCE
The call handle is for a conference call, that is, the application's connection to the conference bridge in the switch.

Not extensible. All 32 bits are reserved.

The origin of a call is stored in the call's LINECALLINFO structure.

See Also

LINEADDRESSCAPS, LINECALLINFO


LINECALLPARAMFLAGS_ Constants

The LINECALLPARAMFLAGS_ constants describe various status flags about a call.

LINECALLPARAMFLAGS_SECURE
Set up the call as secure.
LINECALLPARAMFLAGS_IDLE
Originate the call on an idle call appearance, and do not join a call in progress.
LINECALLPARAMFLAGS_BLOCKID
Conceal the originator identity (block caller ID).
LINECALLPARAMFLAGS_ORIGOFFHOOK
Automatically take the originator's phone off hook.
LINECALLPARAMFLAGS_DESTOFFHOOK
Automatically take the called party's phone off hook.

Not extensible. All 32 bits are reserved.

See Also

LINECALLINFO, LINECALLPARAMS, TSPI_lineGetCallInfo, TSPI_lineMakeCall,


LINECALLPARTYID_ Constants

The LINECALLPARTYID_ bit-flag constants describe the nature of the information available about the parties involved in a call.

LINECALLPARTYID_BLOCKED
Party identifier information is not available because it has been blocked by the remote party.
LINECALLPARTYID_OUTOFAREA
Caller ID information for the call is not available because it is not propagated all the way by the network.
LINECALLPARTYID_NAME
Party identifier information consists of the party's name (as, for example, from a directory kept inside the switch).
LINECALLPARTYID_ADDRESS
Party identifier information consists of the party's address in dialable address format.
LINECALLPARTYID_PARTIAL
Party identifier information is valid, but is limited to partial information only.
LINECALLPARTYID_UNKNOWN
Party identifier information is currently unknown but can become known later.
LINECALLPARTYID_UNAVAIL
Party identifier information is not available and cannot become known later. Information may be unavailable for unspecified reasons. For example, the information was not delivered by the network, was ignored by the service provider, and so forth.

Not extensible. All 32 bits are reserved.

LINECALLPARTYID describes for each of the possible parties involved in a call how the party identifier information is formatted. This information is supplied in the LINECALLINFO data structure.

See Also

LINECALLINFO


LINECALLREASON_ Constants

The LINECALLREASON_ bit-flag constants describe the reason for a call.

LINECALLREASON_DIRECT
This is a direct inbound or outbound call.
LINECALLREASON_FWDBUSY
This call was forwarded from another extension that was busy at the time of the call.
LINECALLREASON_FWDNOANSWER
The call was forwarded from another extension that didn't answer the call after some number of rings.
LINECALLREASON_FWDUNCOND
The call was forwarded unconditionally from another number.
LINECALLREASON_PICKUP
The call was picked up from another extension.
LINECALLREASON_UNPARK
The call was retrieved as a parked call.
LINECALLREASON_REDIRECT
The call was redirected to this station.
LINECALLREASON_CALLCOMPLETION
The call was the result of a call completion request.
LINECALLREASON_TRANSFER
The call has been transferred from another number.
LINECALLREASON_REMINDER
The call is a reminder (or "recall") that the user has a call parked or on hold for (potentially) a long time.
LINECALLREASON_UNKNOWN
The reason for the call is currently unknown but can become known later.
LINECALLREASON_UNAVAIL
The reason for the call is unavailable and cannot become known later.

Not extensible. All 32 bits are reserved.

The LINECALLREASON_ constants are used in the dwReason member of the LINECALLINFO data structure.

See Also

LINECALLINFO, TSPI_lineGetCallInfo


LINECALLSELECT_ Constants

The LINECALLSELECT_ bit-flag constants describe which calls are to be selected.

LINECALLSELECT_LINE
Selects calls on this specified line device.
LINECALLSELECT_ADDRESS
Selects call on the specified address.
LINECALLSELECT_CALL
Selects related calls to the specified call. Examples are the parties in a conference call.

Not extensible. All 32 bits are reserved.

This constant is used in the functions listed below to specify a selection (scope) of the calls that are requested.

See Also

TSPI_lineGetID, TSPI_lineSetMediaControl, TSPI_lineSetTerminal


LINECALLSTATE_ Constants

The LINECALLSTATE_ bit-flag constants describe the call states a call can be in.

LINECALLSTATE_IDLE
The call is idle; no call actually exists.
LINECALLSTATE_OFFERING
The call is being offered to the station, signaling the arrival of a new call. In some environments, a call in the offering state does not automatically alert the user; alerting is done by the switch instructing the line to ring. It does not affect any call states.
LINECALLSTATE_ACCEPTED
The call was offering and has been accepted. This indicates to other (monitoring) applications that the current owner application has claimed responsibility for answering the call. In ISDN, this also initiates alerting to both parties.
LINECALLSTATE_DIALTONE
The call is receiving a dial tone from the switch, which means that the switch is ready to receive a dialed number.
LINECALLSTATE_DIALING
Destination address information (a phone number) is being sent to the switch over the call. Note that the operation TSPI_lineGenerateDigits does not place the line into the dialing state.
LINECALLSTATE_RINGBACK
The call is receiving ringback from the called address. Ringback indicates that the other station has been reached and is being alerted.
LINECALLSTATE_BUSY
The call is receiving a busy tone. A busy tone indicates that the call cannot be completed because either a circuit (trunk) or the remote party's station are in use.
LINECALLSTATE_SPECIALINFO
Special information is sent by the network. Special information is typically sent when the destination cannot be reached.
LINECALLSTATE_CONNECTED
The call has been established and the connection is made. Information is able to flow over the call between the originating address and the destination address.
LINECALLSTATE_PROCEEDING
Dialing has completed and the call is proceeding through the switch or telephone network.
LINECALLSTATE_ONHOLD
The call is on hold by the switch.
LINECALLSTATE_CONFERENCED
The call is currently a member of a multiparty conference call.
LINECALLSTATE_ONHOLDPENDCONF
The call is currently on hold while it is being added to a conference.
LINECALLSTATE_ONHOLDPENDTRANSFER
The call is currently on hold awaiting transfer to another number.
LINECALLSTATE_DISCONNECTED
The remote party has disconnected from the call.
LINECALLSTATE_UNKNOWN
The state of the call is not known. This can be due to limitations of the call-progress detection implementation.

The high-order 8 bits can define a device-specific substate of any of the predefined states, provided that one of the LINECALLSTATE_ bits defined above is also set. The low-order 24 bits are reserved for predefined states.

The LINECALLSTATE_ constants are used as parameters by the LINE_CALLSTATE message sent to the application; the message carries the new call state that the call transitioned to. These constants are also used in members of the LINECALLSTATUS structure, returned by the TSPI_lineGetCallStatus function.

See Also

LINE_CALLSTATE, LINECALLSTATUS, TSPI_lineGetCallStatus


LINEDEVCAPFLAGS_ Constants

The LINEDEVCAPFLAGS_ bit-flag constants are a collection of BOOLEANs describing various line device capabilities.

LINEDEVCAPFLAGS_CROSSADDRCONF
Specify whether calls on different addresses on this line can be conferenced.
LINEDEVCAPFLAGS_HIGHLEVCOMP
Specify whether high-level compatibility information elements are supported on this line.
LINEDEVCAPFLAGS_LOWLEVCOMP
Specify whether low-level compatibility information elements are supported on this line.
LINEDEVCAPFLAGS_MEDIACONTROL
Specify whether media control operations are available for calls at this line.
LINEDEVCAPFLAGS_MULTIPLEADDR
Specify whether TSPI_lineMakeCall or TSPI_lineDial is able to deal with multiple addresses at once (as for inverse multiplexing).
LINEDEVCAPFLAGS_CLOSEDROP
Specify whether the service provider drops (clears) active calls when all applications have closed the open line. If TRUE, the service provider drops all calls on the line when all applications have closed the line. If FALSE, the service provider keeps calls active. The service provider typically sets this to FALSE if some other device can keep the call alive, for example, if an analog line connects directly to the computer and phoneset in a party-line configuration, the offhook phone will automatically keep the call active even after the computer powers down.
LINEDEVCAPFLAGS_DIALBILLING
LINEDEVCAPFLAGS_DIALQUIET
LINEDEVCAPFLAGS_DIALDIALTONE
These flags indicate whether the "$", "@", or "W" dialable string modifier is supported for a given line device. It is TRUE if the modifier is supported; FALSE otherwise. The "?" (prompt user to continue dialing) is never supported by a line device. These flags allow an application to determine "up front" which modifiers would result in the generation of a LINEERR_. The application has the choice of pre-scanning dialable strings for unsupported characters, or passing the "raw" string from lineTranslateAddress directly to the provider as part of lineMakeCall (or lineDial), and letting the function generate an error to tell it which unsupported modifier occurs first in the string.

Not extensible. All 32 bits are reserved.

See Also

LINEDEVCAPS, TSPI_lineDial, TSPI_lineMakeCall


LINEDEVSTATE_ Constants

The LINEDEVSTATE_ bit-flag constants describe various line status events.

LINEDEVSTATE_OTHER
Device-status items other than those listed below have changed.
LINEDEVSTATE_RINGING
The switch tells the line to alert the user. This should be sent repeatedly in a LINE_LINEDEVSTATE message, once for each ring cycle. On a POTS device, the service provider can send the message whenever the central office sends ring voltage. On digital devices such as ISDN, the service provider may need to synthesize the repetition of the message if the switch generates only one ring request. Each repetition of the message should show the ring count increasing, so that toll save functions work properly.
LINEDEVSTATE_CONNECTED
The line was previously disconnected and is now connected to TAPI.
LINEDEVSTATE_DISCONNECTED
This line was previously connected and is now disconnected from TAPI.
LINEDEVSTATE_MSGWAITON
The "message" waiting indicator is turned on.
LINEDEVSTATE_MSGWAITOFF
The "message waiting" indicator is turned off.
LINEDEVSTATE_INSERVICE
The line is connected to TAPI. This happens when TAPI is first activated, or when the line wire is physically plugged in and in-service at the switch while TAPI is active.
LINEDEVSTATE_OUTOFSERVICE
The line is out of service at the switch or physically disconnected. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_MAINTENANCE
Maintenance is being performed on the line at the switch. TAPI cannot be used to operate on the line device.
LINEDEVSTATE_OPEN
The line has been opened by another application.
LINEDEVSTATE_CLOSE
The line has been closed by another application.
LINEDEVSTATE_NUMCALLS
The number of calls on the line device has changed.
LINEDEVSTATE_NUMCOMPLETIONS
The number of outstanding call completions on the line device has changed.
LINEDEVSTATE_TERMINALS
The terminal settings have changed. This can happen, for example, if multiple line devices share terminals (for example, two lines sharing a phone terminal).
LINEDEVSTATE_ROAMMODE
The roam mode of the line device has changed.
LINEDEVSTATE_BATTERY
The battery level has changed significantly (cellular).
LINEDEVSTATE_SIGNAL
The signal level has changed significantly (cellular).
LINEDEVSTATE_DEVSPECIFIC
The line's device-specific information has changed.
LINEDEVSTATE_REINIT
Items have changed in the configuration of line devices. To become aware of these changes (as for the appearance of new line devices) the application should reinitialize its use of TAPI.
LINEDEVSTATE_LOCK
This value is most often used with line devices associated with cellular phones. Many cellular phones have a security mechanism that requires the entry of a password to enable the phone to place calls. This value can be used to indicate to TAPI and its client applications that the phone is locked and cannot place calls until the password is entered on the user interface of the phone, so that the application can present an appropriate alert to the user.
LINEDEVSTATE_REMOVED
The device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A LINE_LINEDEVSTATE message with this value will normally be immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized will result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass it along to applications which have negotiated this or a subsequent API version; applications negotiating a previous API version will not receive any notification.

Not extensible. All 32 bits are reserved.

See Also

LINE_ADDRESSSTATE, LINE_ CLOSE, LINE_LINEDEVSTATE, TSPI_lineForward, TSPI_lineGetLineDevStatus


LINEDEVSTATUSFLAGS_ Constants

The LINEDEVSTATUSFLAGS_ bit-flag constants describe a collection of BOOLEAN line device status items.

LINEDEVSTATUSFLAGS_CONNECTED
Specify whether the line is connected to TAPI. If TRUE, the line is connected, TAPI is able to operate on the line device. If FALSE, the line is disconnected, and the application is unable to control the line device through TAPI.
LINEDEVSTATUSFLAGS_MSGWAIT
Indicate whether the line has a message waiting. If TRUE, a message is waiting; if FALSE, no message is waiting.
LINEDEVSTATUSFLAGS_INSERVICE
Indicate whether the line is in service. If TRUE, the line is in service; if FALSE, the line is out of service.
LINEDEVSTATUSFLAGS_LOCKED
The bit represented by this value is most often used with line devices associated with cellular phones. Many cellular phones have a security mechanism that requires the entry of a password to enable the phone to place calls. The bit represented by this value may be used to indicate to TAPI and its client applications that the phone is locked and cannot place calls until the password is entered on the user interface of the phone, so that the application can present an appropriate alert to the user.

Not extensible. All 32 bits are reserved.

See Also

LINECALLSTATUS


LINEDIALTONEMODE_ Constants

The LINEDIALTONEMODE_ bit-flag constants describe different types of dial tones. A special dial tone typically carries a special meaning (as with message waiting).

LINEDIALTONEMODE_NORMAL
This is a "normal" dial tone, which is typically a continuous tone.
LINEDIALTONEMODE_SPECIAL
A special dial tone indicating a certain condition (known by the switch or network) is currently in effect. Special dial tones typically use an interrupted tone. As with a normal dial tone, this indicates that the switch is ready to receive the number to be dialed.
LINEDIALTONEMODE_INTERNAL
This an internal dial tone, as within a PBX.
LINEDIALTONEMODE_EXTERNAL
This is an external (public network) dial tone.
LINEDIALTONEMODE_UNKNOWN
The dial tone mode is currently unknown, but can become known later.
LINEDIALTONEMODE_UNAVAIL
The dial tone mode is unavailable and cannot become known.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

The LINEDIALTONEMODE_ constants are used in the LINECALLSTATUS data structure for a call in the dialtone state.

See Also

LINECALLSTATUS


LINEDIGITMODE_ Constants

The LINEDIGITMODE_ constants describe different types of inband digit generation.

LINEDIGITMODE_PULSE
Uses rotary pulse sequences to signal digits. Valid digits are '0' through '9'.
LINEDIGITMODE_DTMF
Uses DTMF tones to signal digits. Valid digits are '0' through '9', '*', '#', 'A', 'B', 'C', and 'D'.
LINEDIGITMODE_DTMFEND
Uses DTMF tones to signal digits and detect the down edges. Valid digits are '0' through '9', '*', '#', 'A', 'B', 'C', and 'D'.

Not extensible. All 32 bits are reserved.

A digit mode can be specified when generating or detecting digits. Note that pulse digits are generated by making and breaking the local loop circuit. These pulses are absorbed by the switch. The remote end merely observes this as a series of inband audio clicks. Detecting digits sent as pulses must therefore be able to detect these sequences of one to ten audible clicks.

See Also

LINEMEDIACONTROLDIGIT, TSPI_lineGatherDigits, TSPI_lineGenerateDigits, TSPI_lineMonitorDigits, TSPI_lineSetMediaControl


LINEDISCONNECTMODE_ Constants

The LINEDISCONNECTMODE_ bit-flag constants describe different reasons for a remote disconnect request. A disconnect mode is available as a call status to the application after the call state transitions to disconnected.

LINEDISCONNECTMODE_NORMAL
A "normal" disconnect request by the remote party; the call was terminated normally.
LINEDISCONNECTMODE_UNKNOWN
The reason for the disconnect request is unknown, but can become known later.
LINEDISCONNECTMODE_REJECT
The remote user has rejected the call.
LINEDISCONNECTMODE_PICKUP
The call was picked up from elsewhere.
LINEDISCONNECTMODE_FORWARDED
The call was forwarded by the switch.
LINEDISCONNECTMODE_BUSY
The remote user's station is busy.
LINEDISCONNECTMODE_NOANSWER
The remote user's station does not answer.
LINEDISCONNECTMODE_BADADDRESS
The destination address in invalid.
LINEDISCONNECTMODE_UNREACHABLE
The remote user could not be reached.
LINEDISCONNECTMODE_CONGESTION
The network is congested.
LINEDISCONNECTMODE_INCOMPATIBLE
The remote user's station equipment is incompatible for the type of call requested.
LINEDISCONNECTMODE_UNAVAIL
The reason for the disconnect is unavailable and cannot become known later.
LINEDISCONNECTMODE_NODIALTONE
A dial tone was not detected within a service-provider defined timeout, at a point during dialing when one was expected (such as at a "W" in the dialable string). This can also occur without a service-provider-defined timeout period or without a value specified in the dwWaitForDialTone member of the LINEDIALPARAMS structure.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

A remote disconnect request for a given call results in the call state transitioning to the disconnected state and a LINE_CALLSTATE messages is sent to the application. The LINEDISCONNECTMODE_ constants provide details about the remote disconnect request. It is available in the call's LINECALLSTATUS structure when the call is in the disconnected state. While a call is in this state, the application is still allowed to query the calls information and status. For example, user-to-user information received as part of the remote disconnect is available then. The application can clear a disconnected call by dropping the call.

See Also

LINE_CALLSTATE, LINECALLSTATUS, LINEDIALPARAMS


LINEERR_ Constants

This is the list of error codes that the implementation may return when invoking operations on lines, addresses, or calls. For more information about which of these error codes a particular function can return, see the individual function descriptions in TSPI Functions.

LINEERR_ADDRESSBLOCKED
The specified address is blocked from being dialed on the specified call.
LINEERR_ALLOCATED
The line cannot be opened due to a "persistent" condition, such as that of a serial port being exclusively opened by another process.
LINEERR_BEARERMODEUNAVAIL
The bearer mode member in LINECALLPARAMS is invalid, the bearer mode specified in LINECALLPARAMS is not available, or the call's bearer mode cannot be changed to the specified bearer mode.
LINEERR_CALLUNAVAIL
All call appearances on the specified address are currently in use or allocated.
LINEERR_COMPLETIONOVERRUN
The maximum number of outstanding call completions has been exceeded.
LINEERR_CONFERENCEFULL
The maximum number of parties for a conference has been reached or the requested number of parties cannot be satisfied.
LINEERR_DIALBILLING
The dialable address parameter contains dialing control characters that are not processed by the service provider.
LINEERR_DIALDIALTONE
The dialable address parameter contains dialing control characters that are not processed by the service provider.
LINEERR_DIALPROMPT
The dialable address parameter contains dialing control characters that are not processed by the service provider.
LINEERR_DIALQUIET
The dialable address parameter contains dialing control characters that are not processed by the service provider.
LINEERR_INCOMPATIBLEAPIVERSION
The passed TSPI version or version range did not match an interface version definition supported by the service provider.
LINEERR_INCOMPATIBLEEXTVERSION
The passed extension version range did not contain an interface definition version supported by the service provider, or the passed TSPI version did not match an extension version definition supported by the service provider.
LINEERR_INIFILECORRUPT
A required INI file was corrupt in a way that the removal procedure was unable to correct or handle.
LINEERR_INUSE
The line device is in use and cannot currently be configured, allow a party to be added, allow a call to be answered, or allow a call to be placed.
LINEERR_INVALADDRESS
The specified address is invalid, is not assigned to the specified line, contains invalid characters or digits, or is not valid for redirection. This error is also returned if the destination address contains dialing control characters (W, @, $, ?) that are not supported by the server provider.
LINEERR_INVALADDRESSID
The specified address identifier, such as the dwAddressID parameter or in the LINECALLPARAMS structure, is invalid or is out of range.
LINEERR_INVALADDRESSMODE
The address mode specified in LINECALLPARAMS is invalid.
LINEERR_INVALADDRESSSTATE
The specified address state is invalid.
LINEERR_INVALBEARERMODE
The bearer mode, such as specified in LINECALLPARAMS, is invalid.
LINEERR_INVALCALLCOMPLMODE
The specified completion is invalid.
LINEERR_INVALCALLHANDLE
One or more specified call or device handles are invalid.
LINEERR_INVALCALLPARAMS
The specified call parameters, such as in the LINECALLPARAMS structure, are invalid.
LINEERR_INVALCALLSELECT
The specified select parameter is invalid.
LINEERR_INVALCALLSTATE
One or more of the specified calls are not in a valid state for the requested operation.
LINEERR_INVALCALLSTATELIST
The specified call state list is invalid.
LINEERR_INVALCOMPLETIONID
The completion identifier is invalid.
LINEERR_INVALCONFCALLHANDLE
The specified call handle for the conference call is invalid or is not a handle for a conference call.
LINEERR_INVALCOUNTRYCODE
One or more of the specified country codes, such as in the LINEFORWARDLIST structure, are invalid.
LINEERR_INVALDEVICECLASS
The line device has no associated device for the given device class, or the specified line does not support the indicated device class.
LINEERR_INVALDIGITLIST
The specified digit list is invalid.
LINEERR_INVALDIGITMODE
The specified digit mode is invalid or not available.
LINEERR_INVALDIGITS
The specified termination digits are not valid.
LINEERR_INVALFEATURE
The dwFeature parameter is invalid.
LINEERR_INVALGROUPID
The specified group identifier is invalid.
LINEERR_INVALLINEHANDLE
The specified call, device, line device, or line handle is invalid.
LINEERR_INVALLINESTATE
The line is currently not in a state in which this operation can be performed.
LINEERR_INVALMEDIALIST
The specified media list is invalid.
LINEERR_INVALMEDIAMODE
One or more media modes specified as a parameter, in the media mode member in the LINECALLPARAMS structure or in a list, is invalid or not supported by the the service provider.
LINEERR_INVALMESSAGEID
The number given in dwMessageID is outside the range specified by the dwNumCompletionMessages member in the LINEADDRESSCAPS structure.
LINEERR_INVALPARAM
A parameter or structure pointed to by a parameter contains invalid information.
LINEERR_INVALPARKMODE
The specified park mode is invalid.
LINEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.
LINEERR_INVALPOINTER
The lpDialParams pointer is non-NULL and invalid.
LINEERR_INVALPOINTER
This error return value is returned if lpToneList has a non-NULL value that is invalid.
LINEERR_INVALRATE
One or more rates, such as specified in the LINECALLPARAMS structure, are invalid.
LINEERR_INVALTERMINALID
The specified terminal mode parameter is invalid.
LINEERR_INVALTERMINALMODE
The specified terminal modes parameter is invalid.
LINEERR_INVALTIMEOUT
The values of either or both of the parameters dwFirstDigitTimeout or dwInterDigitTimeout fall outside the valid range specified by LINEDEVCAPS, or timeouts are not supported.
LINEERR_INVALTONE
The specified tone structure or custom tone does not represent or describe a valid tone, or is made up of too many frequencies.
LINEERR_INVALTONELIST
The specified tone list is invalid.
LINEERR_INVALTONEMODE
The specified tone mode parameter is invalid.
LINEERR_NODEVICE
The line device has no associated device for the given device class.
LINEERR_NODRIVER
This error can be returned from a function when the driver finds that one of its components is corrupt in a way that was not detected at initialization. For example, if a service provider consists of multiple components such as a Virtual Device Driver (VxD), in addition to the usual DLL (exporting the TSPI interface and having the .TSP extension), LINEERR_NODRIVER can be returned to indicate that the VxD component was missing. Advise the user to use the Telephony Control Panel to correct the problem.
LINEERR_NOMEM
Unable to allocate or lock memory.
LINEERR_NOMULTIPLEINSTANCE
TSPI_providerInit was called more than once without an intervening TSPI_providerShutdown (that is, an attempt was made to invoke multiple instances of the provider), when the provider does not support multiple instances.
LINEERR_OPERATIONFAILED
The installation or configuration failed or was cancelled by the user. Alternately, the operation failed for an unknown or unspecified reason.
LINEERR_OPERATIONUNAVAIL
The operation is not available.
LINEERR_RATEUNAVAIL
The service provider currently does not have enough bandwidth available for the rate specified in LINECALLPARAMS.
LINEERR_RATEUNAVAIL
The service provider does currently not have enough bandwidth available for the specified rate, such as given in LINECALLPARAMS.
LINEERR_RESOURCEUNAVAIL
The operation cannot be completed because of resource overcommitment.
LINEERR_RESOURCEUNAVAIL
The operation cannot be completed because of resource overcommitment. This return value may also be returned if too many terminals are set, due either to hardware limitations or to service provider/device driver limitations.
LINEERR_STRUCTURETOOSMALL
The dwTotalSize member of a structure, such as a VARSTRING or LINEFORWARDLIST structure, does not specify enough memory to contain the fixed portion of the structure. The dwNeededSize member has been set to the amount required.
LINEERR_USERUSERINFOTOOBIG
The string containing user-user information is either too long or exceeds the maximum number of bytes specified in one of these members of the LINEDEVCAPS structure: dwUUIAcceptSize, dwUUIAnswerSize, dwUUIDropSize, dwUUIMakeCallSize, or dwUUISendUserUserInfoSize.

The values 0xC0000000 through 0xFFFFFFFF are available for device-specific extensions. The values 0x80000000 through 0xBFFFFFFF are reserved, while 0x00000000 through 0x7FFFFFFF are used as request identifiers.

See Also

LINEADDRESSCAPS, LINECALLPARAMS, LINEDEVCAPS, LINEFORWARDLIST, TSPI_providerInit, TSPI_providerShutdown, VARSTRING,


LINEFEATURE_ Constants

The LINEFEATURE_ constants list the operations that can be invoked on a line using this API.

LINEFEATURE_DEVSPECIFIC
Device-specific operations can be used on the line.
LINEFEATURE_DEVSPECIFICFEAT
Device-specific features can be used on the line.
LINEFEATURE_FORWARD
Forwarding of all addresses can be used on the line.
LINEFEATURE_MAKECALL
An outbound call can be placed on this line using an unspecified address.
LINEFEATURE_SETMEDIACONTROL
Media control can be set on this line.
LINEFEATURE_SETTERMINAL
Terminal modes for this line can be set.

Not extensible. All 32 bits are reserved.

This constant is used both in LINEDEVCAPS (returned by TSPI_lineGetDevCaps) and in LINEDEVSTATUS (returned by TSPI_lineGetLineDevStatus). LINEDEVCAPS reports the availability of the line features by the service provider (mainly the switch) for a given line. An application makes this determination when it initializes. LINEDEVSTATUS reports for a given line which line features can actually be invoked while the line is in the current state. An application would make this determination dynamically, after line state changes, typically caused by address or call-related activities on the line.

See Also

LINEDEVCAPS, LINEDEVSTATUS, TSPI_lineGetDevCaps, TSPI_lineGetLineDevStatus


LINEFORWARDMODE_ Constants

The LINEFORWARDMODE_ bit-flag constants describe the conditions under which calls to an address can be forwarded.

LINEFORWARDMODE_UNCOND
Forward all calls unconditionally irrespective of their origin. Use this value when unconditional forwarding for internal and external calls cannot be controlled separately. Unconditional forwarding overrides forwarding on busy and/or no-answer conditions.
LINEFORWARDMODE_UNCONDINTERNAL
Forward all internal calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.
LINEFORWARDMODE_UNCONDEXTERNAL
Forward all external calls unconditionally. Use this value when unconditional forwarding for internal and external calls can be controlled separately.
LINEFORWARDMODE_UNCONDSPECIFIC
Forward all calls that originated at a specified address unconditionally (selective call forwarding).
LINEFORWARDMODE_BUSY
Forward all calls on busy, irrespective of their origin. Use this value when forwarding for internal and external calls on busy and no answer cannot be controlled separately.
LINEFORWARDMODE_BUSYINTERNAL
Forward all internal calls on busy. Use this value when forwarding for internal and external calls on busy and no answer can be controlled separately.
LINEFORWARDMODE_BUSYEXTERNAL
Forward all external calls on busy. Use this value when forwarding for internal and external calls on busy and no answer can be controlled separately.
LINEFORWARDMODE_BUSYSPECIFIC
Forward all calls that originated at a specified address on busy (selective call forwarding).
LINEFORWARDMODE_NOANSW
Forward all calls on no answer, irrespective of their origin. Use this value when call forwarding for internal and external calls on no answer cannot be controlled separately.
LINEFORWARDMODE_NOANSWINTERNAL
Forward all internal calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.
LINEFORWARDMODE_NOANSWEXTERNAL
Forward all external calls on no answer. Use this value when forwarding for internal and external calls on no answer can be controlled separately.
LINEFORWARDMODE_NOANSWSPECIFIC
Forward all calls that originated at a specified address on no answer (selective call forwarding).
LINEFORWARDMODE_BUSYNA
Forward all calls on busy/no answer irrespective of their origin. Use this value when forwarding for internal and external calls on busy and no answer cannot be controlled separately.
LINEFORWARDMODE_BUSYNAINTERNAL
Forward all internal calls on busy/no answer. Use this value when call forwarding on busy and no answer cannot be controlled separately for internal calls.
LINEFORWARDMODE_BUSYNAEXTERNAL
Forward all external calls on busy/no answer. Use this value when call forwarding on busy and no answer cannot be controlled separately for internal calls.
LINEFORWARDMODE_BUSYNASPECIFIC
Forward all calls that originated at a specified address on busy/no answer (selective call forwarding).

Not extensible. All 32 bits are reserved.

The bit flags defined by LINEFORWARDMODE_ are not orthogonal. Unconditional forwarding ignores any specific condition such as busy or no answer. If unconditional forwarding is not in effect, forwarding on busy and no answer can either be controlled separately or not. If controlled separately, the BUSY and NOANSW flags can be used separately. If not controlled separately, the flag BUSYNA must be used. Similarly, if forwarding of internal and external calls can be controlled separately, INTERNAL and EXTERNAL flags can be used separately, otherwise the combination is used.

Address capabilities indicate for each address assigned to a line the forwarding mode(s) that are available. An application can use TSPI_lineForward to set forwarding conditions at the switch.

See Also

LINE_ADDRESSSTATE, LINEADDRESSCAPS, LINEADDRESSSTATUS, LINEFORWARD, TSPI_lineForward, TSPI_lineGetAddressCaps


LINEGATHERTERM_ Constants

The LINEGATHERTERM_ bit-flag constants describe the conditions under which buffered digit gathering is terminated.

LINEGATHERTERM_BUFFERFULL
The requested number of digits has been gathered. The buffer is full.
LINEGATHERTERM_TERMDIGIT
One of the termination digits matched a received digit. The matched termination digit is the last digit in the buffer.
LINEGATHERTERM_FIRSTTIMEOUT
The first digit timeout expired. The buffer contains no digits.
LINEGATHERTERM_INTERTIMEOUT
The inter digit timeout expired. The buffer contains at least one digit.
LINEGATHERTERM_CANCEL
The request was canceled by this application, by another application, or because the call terminated.

Not extensible. All 32 bits are reserved.

See Also

LINE_GATHERDIGITS, TSPI_lineGatherDigits


LINEGENERATETERM_ Constants

The LINEGENERATETERM_ bit-flag constants describe the conditions under which digit or tone generation is terminated.

LINEGENERATETERM_DONE
The requested number of digits have been generated, or requested tones have been generated for the requested duration.
LINEGENERATETERM_CANCEL
The digit or tone generation request was canceled by this application, by another application, or because the call terminated. LINEGENERATETERM_CANCEL can also be returned when digit or tone generation cannot be completed due to an internal failure of the service provider.

Not extensible. All 32 bits are reserved.

See Also

LINE_GENERATE, TSPI_lineGenerateDigits, TSPI_lineGenerateTone


LINEMEDIACONTROL_ Constants

The LINEMEDIACONTROL_ bit-flag constants describe a set of generic operations on media streams. The interpretations are determined by the media stream. The line device must have the media control capability in order for any media control operations to be effective.

LINEMEDIACONTROL_NONE
No change is to be made to the media stream.
LINEMEDIACONTROL_START
Start the media stream.
LINEMEDIACONTROL_RESET
Reset the media stream. Provide the effect of an end-of-input. All buffers are released.
LINEMEDIACONTROL_PAUSE
Temporarily pause the media stream.
LINEMEDIACONTROL_RESUME
Resume a paused media stream.
LINEMEDIACONTROL_RATEUP
The speed of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_RATEDOWN
The speed of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_RATENORMAL
The speed of the media stream is returned to normal.
LINEMEDIACONTROL_VOLUMEUP
The amplitude of the media stream is increased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMEDOWN
The amplitude of the media stream is decreased by some stream-defined quantity.
LINEMEDIACONTROL_VOLUMENORMAL
The amplitude of the media stream is returned to normal.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Media control is provided as a way of improving the performance of actions on media streams on calls in response to telephony related events. The application should normally manage a media stream through the media-specific API; the media control functionality provided here is not intended as a replacemenet for the native media APIs.

Media control actions can be associated with the detection of digits, the detection of tones, the transition into a call state, and the detection of a media mode. Consult a line's device capabilities to determine whether media control is available on a line.

See Also

LINEMEDIACONTROLCALLSTATE, LINEMEDIACONTROLDIGIT, LINEMEDIACONTROLMEDIA, LINEMEDIACONTROLTONE, TSPI_lineSetMediaControl


LINEMEDIAMODE_ Constants

The LINEMEDIAMODE_ constants describe the common media modes (the datatypes of a media stream) on calls. They are used in a system of priority ordering when presenting a new incoming call of UNKNOWN media mode with multiple specific media mode flags set. The priority determines which media-handling application the call should be presented to first. (Extension media modes are considered to all have a lower priority order than the common media modes.)

LINEMEDIAMODE_UNKNOWN
A media stream exists but its mode is not currently known and may become known later. This corresponds to a call with an unclassified media type. In typical analog telephony environments, an inbound call's media mode can be unknown until after the call has been answered and the media stream filtered to make a determination.
LINEMEDIAMODE_INTERACTIVEVOICE
The presence of voice energy on the call and the call is treated as an interactive call with humans on both ends.
LINEMEDIAMODE_AUTOMATEDVOICE
The presence of voice energy on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DATAMODEM
A data modem session on the call.
LINEMEDIAMODE_G3FAX
A group 3 fax is being sent or received over the call.
LINEMEDIAMODE_TDD
A TDD (Telephony Devices for the Deaf) session on the call.
LINEMEDIAMODE_G4FAX
A group 4 fax is being sent or received over the call.
LINEMEDIAMODE_DIGITALDATA
Digital data is being sent or received over the call.
LINEMEDIAMODE_TELETEX
A teletex session on the call. Teletex is one of the telematic services.
LINEMEDIAMODE_VIDEOTEX
A videotex session on the call. Videotex is one the telematic services.
LINEMEDIAMODE_TELEX
A telex session on the call. Telex is one the telematic services.
LINEMEDIAMODE_MIXED
A mixed session on the call. Mixed is one the ISDN telematic services.
LINEMEDIAMODE_ADSI
An ADSI (Analog Display Services Interface) session on the call.
LINEMEDIAMODE_VOICEVIEW
The media mode of the call is VoiceView.

The high-order 8 bits can be assigned for device-specific extensions. The low-order 24 bits are reserved.

Note that bearer mode and media mode are different notions. The bearer mode of a call is an indication of the quality of the telephone connection as provided primarily by the network. The media mode of a call is an indication of the type of information stream that is exchanged over that call. Group 3 fax and data modem are media modes that use a call with a 3.1kHz voice bearer mode.

See Also

LINE_MONITORMEDIA, LINEMEDIACONTROLMEDIA, TSPI_lineMonitorMedia


LINEPARKMODE_ Constants

The LINEPARKMODE_ bit-flag constants describe different ways of parking calls.

LINEPARKMODE_DIRECTED
Specify directed call park. The address where the call is to be parked must be supplied to the switch.
LINEPARKMODE_NONDIRECTED
Specify nondirected call park. The address where the call is parked is selected by the switch and provided by the switch to the application.

Not extensible. All 32 bits are reserved.

The LINEPARKMODE_ constants are used when parking a call. Consult a line's address device capabilities to find out which park mode is available.

See Also

TSPI_linePark


LINEREMOVEFROMCONF_ Constants

The LINEREMOVEFROMCONF_ scalar constants describe how parties participating in a conference call can be removed from that conference call.

LINEREMOVEFROMCONF_NONE
Parties cannot be removed from the conference call.
LINEREMOVEFROMCONF_LAST
Only the most recently added party can be removed from the conference call
LINEREMOVEFROMCONF_ANY
Any participating party can be removed from the conference call.

Not extensible. All 32 bits are reserved.

See Also

LINEDEVCAPS


LINEROAMMODE_ Constants

The LINEROAMMODE_ bit-flag constants describe the roaming status of a line device.

LINEROAMMODE_UNKNOWN
The roam mode is currently unknown, but can become known later.
LINEROAMMODE_UNAVAIL
The roam mode is unavailable and cannot be known.
LINEROAMMODE_HOME
The line is connected to the home network node.
LINEROAMMODE_ROAMA
The line is connected to the Roam-A carrier and calls are charged accordingly.
LINEROAMMODE_ROAMB
The line is connected to the Roam-B carrier and calls are charged accordingly.

Not extensible. All 32 bits are reserved.

See Also

LINEDEVCAPS


LINESPECIALINFO_ Constants

The LINESPECIALINFO_ bit-flag constants describe special information signals that the network can use to report various reporting and network observation operations. These constants are special coded tone sequences transmitted at the beginning of network advisory recorded announcements.

LINESPECIALINFO_NOCIRCUIT
Special information tone that precedes a no-circuit or emergency announcement (trunk blockage category).
LINESPECIALINFO_CUSTIRREG
Special information tone that precedes a vacant number, AIS, Centrex number change and nonworking station, access code not dialed or dialed in error, and manual intercept operator message (customer irregularity category). LINESPECIALINFO_CUSTIRREG is also reported when billing information is rejected and when the dialed address is blocked at the switch.
LINESPECIALINFO_REORDER
Special information tone that precedes a reorder announcement (equipment irregularity category). LINESPECIALINFO_REORDER is also reported when the telephone is kept offhook too long.
LINESPECIALINFO_UNKNOWN
Specifics about the special information tone are currently unknown but can become known later.
LINESPECIALINFO_UNAVAIL
Specifics about the special information tone are unavailable, and cannot become known.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Special information tones are defined for advisory messages and are not usually used for billing or supervisory purposes.

See Also

LINECALLSTATUS


LINETERMDEV_ Constants

The LINETERMDEV_ bit-flag constants describe different types of terminal devices.

LINETERMDEV_PHONE
The terminal is a phone set.
LINETERMDEV_HEADSET
The terminal is a headset.
LINETERMDEV_SPEAKER
The terminal is an external speaker and microphone.

Not extensible. All 32 bits are reserved.

These constants are used to characterize a line's terminal device. This allows an application to determine the nature of a terminal device.

See Also

LINEDEVCAPS, TSPI_lineSetTerminal


LINETERMMODE_ Constants

The LINETERMMODE_ bit-flag constants describe different types of events on a phone line that can be routed to a terminal device.

LINETERMMODE_BUTTONS
Button press events sent from the terminal to the line.
LINETERMMODE_LAMPS
Lamp events sent from the line to the terminal.
LINETERMMODE_DISPLAY
Display information sent from the line to the terminal.
LINETERMMODE_RINGER
Ringer control information sent from the switch to the terminal.
LINETERMMODE_HOOKSWITCH
Hookswitch events sent from the terminal to the line.
LINETERMMODE_MEDIATOLINE
The unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIAFROMLINE
The unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when routing of both unidirectional channels of a call's media stream can be controlled independently.
LINETERMMODE_MEDIABIDIRECT
The bidirectional media stream associated with a call on the line and the terminal. Use this value when routing of both unidirectional channels of a call's media stream cannot be controlled independently.

Not extensible. All 32 bits are reserved.

These constants describe the classes of control and information streams that can be routed directly between a line device and a terminal device (such as a phone set).

See Also

LINEDEVCAPS, TSPI_lineSetTerminal


LINETERMSHARING_ Constants

The LINETERMSHARING_ bit flag constants describe different ways in which a terminal can be shared between line devices, addresses, or calls.

LINETERMSHARING_PRIVATE
The terminal device is private to a single line device.
LINETERMSHARING_SHAREDEXCL
The terminal device can be used by multiple lines. The last line device to do a TSPI_lineSetTerminal to the terminal for a given terminal mode will have exclusive connection to the terminal for that mode.
LINETERMSHARING_SHAREDCONF
The terminal device can be used by multiple lines. The TSPI_lineSetTerminal requests of the various terminals are "merged" or conferenced at the terminal.

Not extensible. All 32 bits are reserved.

These constants describe the classes of control and information streams that can be routed directly between a line device and a terminal device (such as a phone set).

See Also

LINEDEVCAPS, TSPI_lineSetTerminal


LINETONEMODE_ Constants

The LINETONEMODE_ constants describe different selections used when generating line tones.

LINETONEMODE_CUSTOM
A custom tone, defined by its component frequencies, of type LINEGENERATETONE.
LINETONEMODE_RINGBACK
A ringback tone. Exact definition is service-provider defined.
LINETONEMODE_BUSY
A busy tone. Exact definition is service-provider defined.
LINETONEMODE_BEEP
A beep, such as used to announce the beginning of a recording. Exact definition is service-provider defined.
LINETONEMODE_BILLING
A billing information tone, such as a credit card prompt tone. Exact definition is service-provider-defined.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

These constants are used to define tones to be generated inband over a call to the remote party. Note that tone detection of non-custom tones does not use these constants.

See Also

LINE_GENERATE, LINEGENERATETONE, TSPI_lineGenerateTone


LINETRANSFERMODE_ Constants

The LINETRANSFERMODE_ bit-flag constants describe different ways of resolving call transfer requests.

LINETRANSFERMODE_TRANSFER
The transfer is resolved by transferring the initial call to the consultation call. Both calls become idle to the application.
LINETRANSFERMODE_CONFERENCE
The transfer is resolved by establishing a three-way conference between the application, the party connected to the initial call, and the party connected to the consultation call. A conference call is created when this option is selected.

Not extensible. All 32 bits are reserved.

See Also

TSPI_lineCompleteTransfer


TSPI Phone Device Constants

This section contains a list of the phone device constants in the Telephony SPI.


PHONEBUTTONFUNCTION_ Constants

The PHONEBUTTONFUNCTION_ scalar constants describe the functions commonly assigned to buttons on telephone sets.

PHONEBUTTONFUNCTION_UNKNOWN
A "dummy" function assignment that indicates that the exact function of the button is unknown or has not been assigned.
PHONEBUTTONFUNCTION_CONFERENCE
Initiate a conference call or add a call to a conference call.
PHONEBUTTONFUNCTION_TRANSFER
Initiate a call transfer or complete the transfer of a call.
PHONEBUTTONFUNCTION_DROP
Drop the active call.
PHONEBUTTONFUNCTION_HOLD
Place the active call on hold.
PHONEBUTTONFUNCTION_RECALL
Unhold a call.
PHONEBUTTONFUNCTION_DISCONNECT
Disconnect a call, such as after initiating a transfer.
PHONEBUTTONFUNCTION_CONNECT
Reconnect a call that is on consultation hold.
PHONEBUTTONFUNCTION_MSGWAITON
Turn on a message waiting lamp.
PHONEBUTTONFUNCTION_MSGWAITOFF
Turn off a message waiting lamp.
PHONEBUTTONFUNCTION_SELECTRING
Allow the user to select the ring pattern of the phone.
PHONEBUTTONFUNCTION_ABBREVDIAL
The number to be dialed is indicated using a short, abbreviated number consisting of one or a few digits.
PHONEBUTTONFUNCTION_FORWARD
Initiate or change call forwarding to this phone.
PHONEBUTTONFUNCTION_PICKUP
Pick up a call ringing on another phone.
PHONEBUTTONFUNCTION_RINGAGAIN
Initiate a request to be notified if a call cannot be completed normally because of a busy or no answer.
PHONEBUTTONFUNCTION_PARK
Park the active call on another phone, placing it on hold there.
PHONEBUTTONFUNCTION_REJECT
Reject an inbound call before the call has been answered.
PHONEBUTTONFUNCTION_REDIRECT
Redirect an inbound call to another extension before the call has been answered.
PHONEBUTTONFUNCTION_MUTE
Mute the phone's microphone device.
PHONEBUTTONFUNCTION_VOLUMEUP
Increase the volume of audio through the phone's handset speaker or speakerphone.
PHONEBUTTONFUNCTION_VOLUMEDOWN
Decrease the volume of audio through the phone's handset speaker or speakerphone.
PHONEBUTTONFUNCTION_SPEAKERON
Turn the phone's external speaker on.
PHONEBUTTONFUNCTION_SPEAKEROFF
Turn the phone's external speaker off.
PHONEBUTTONFUNCTION_FLASH
Generate the equivalent of an onhook/offhook sequence. A flash typically indicates that any digits typed next are to be understood as commands to the switch. On many switches, places an active call on consultation hold.
PHONEBUTTONFUNCTION_DATAON
Indicate that the next call is a data call.
PHONEBUTTONFUNCTION_DATAOFF
Indicate that the next call is not a data call.
PHONEBUTTONFUNCTION_DONOTDISTURB
Place the phone in "do not disturb" mode; incoming calls receive a busy signal or are forwarded to an operator or voice mail system.
PHONEBUTTONFUNCTION_INTERCOM
Connect to the intercom to broadcast a page.
PHONEBUTTONFUNCTION_BRIDGEDAPP
Select a particular appearance of a bridged address.
PHONEBUTTONFUNCTION_BUSY
Make the phone appear "busy" to incoming calls.
PHONEBUTTONFUNCTION_CALLAPP
Select a particular call appearance.
PHONEBUTTONFUNCTION_DATETIME
Cause the phone to display current date and time; this information is sent by the switch.
PHONEBUTTONFUNCTION_DIRECTORY
Call up directory service from the switch.
PHONEBUTTONFUNCTION_COVER
Forward all calls destined for this phone to another phone used for coverage.
PHONEBUTTONFUNCTION_CALLID
Request display of caller ID on the phone's display.
PHONEBUTTONFUNCTION_LASTNUM
Redial last number dialed.
PHONEBUTTONFUNCTION_NIGHTSRV
Place the phone in the mode it is configured for during night hours.
PHONEBUTTONFUNCTION_SENDCALLS
Send all calls to another phone used for coverage; same as PHONEBUTTONFUNCTION_COVER.
PHONEBUTTONFUNCTION_MSGINDICATOR
Control the message indicator lamp.
PHONEBUTTONFUNCTION_REPDIAL
Repertory dialing;the number to be dialed is provided as a shorthand following pressing of this button.
PHONEBUTTONFUNCTION_SETREPDIAL
Programs the shorthand-to-phone number mappings accessible by means of repertory dialing (the "REPDIAL" button).
PHONEBUTTONFUNCTION_SYSTEMSPEED
The number to be dialed is provided as a shorthand following pressing of this button. The mappings for system speed dialing are configured inside the switch.
PHONEBUTTONFUNCTION_STATIONSPEED
The number to be dialed is provided as a shorthand following pressing of this button. The mappings for station speed dialing are specific to this station (phone).
PHONEBUTTONFUNCTION_CAMPON
Camp on an extension that returns a busy indication. When the remote station returns to idle, the phone rings with a distinctive pattern. Picking up the local phone reinitiates the call.
PHONEBUTTONFUNCTION_SAVEREPEAT
When pressed while a call or call attempt is active, it will remember that call's number or command. When pressed while no call is active (such as during dial tone), it repeats the most saved command.
PHONEBUTTONFUNCTION_QUEUECALL
Queue a call to an outside number after it encounters a trunk-busy indiction. When a trunk later becomes available, the phone rings with a distinctive pattern. Picking up the local phone reinitiates the call.
PHONEBUTTONFUNCTION_NONE
A "dummy" function assignment that indicates the button does not have a function.

Values in the range 0x80000000 to 0xFFFFFFFF can be assigned for device-specific extensions; values in the range 0x00000000 to 0x7FFFFFFF are reserved.

The PHONEBUTTONFUNCTION_ constants have values commonly found on current telephone sets. These button functions can be used to invoke the corresponding function from the switch using TSPI_lineDevSpecificFeature. Note that TAPI does not define the semantics of the button functions, it only provides access to the corresponding function. The behavior associated with each of the function values described earlier is generic and can vary based on the telephony environment.

See Also

PHONE_BUTTON, TSPI_lineDevSpecificFeature, TSPI_phoneGetButtonInfo, TSPI_phoneSetButtonInfo


PHONEBUTTONMODE_ Constants

The PHONEBUTTONMODE_ bit-flag constants describe the button classes.

PHONEBUTTONMODE_DUMMY
Used to describe a button/lamp position that has no corresponding button, but has only a lamp.
PHONEBUTTONMODE_CALL
The button is assigned to a call appearance.
PHONEBUTTONMODE_FEATURE
The button is assigned to requesting features from the switch, such as hold, conference, and transfer.
PHONEBUTTONMODE_KEYPAD
The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'.
PHONEBUTTONMODE_LOCAL
The button is a local function button, such as mute or volume control.
PHONEBUTTONMODE_DISPLAY
The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.

Not extensible. All 32 bits are reserved.

This enumeration type is used in the PHONECAPS data structure to describe the meaning associated with the phone's buttons.

See Also

PHONE_BUTTON, PHONEBUTTONINFO, PHONECAPS, TSPI_phoneGetButtonInfo, TSPI_phoneGetDevCaps, TSPI_phoneSetButtonInfo


PHONEBUTTONSTATE_ Constants

The PHONEBUTTONSTATE_ bit-flag constants describe various button positions.

PHONEBUTTONSTATE_UP
The button is in the "up" state.
PHONEBUTTONSTATE_DOWN
The button is in the "down" state (pressed down).

Not extensible. All 32 bits are reserved.

See Also

PHONE_BUTTON, PHONECAPS, TSPI_phoneGetDevCaps, TSPI_phoneSetStatusMessages


PHONEERR_ Constants

This is the list of error codes that the implementation can return when invoking operations on phone devices. For more information on which error codes a specific function can return, see TSPI Functions.

PHONEERR_ALLOCATED
The specified resource is already allocated.
PHONEERR_BADDEVICEID
The specified phone device identifier is invalid or out of range.
PHONEERR_INCOMPATIBLEAPIVERSION
The passed TSPI version did not match an interface version definition supported by the service provider.
PHONEERR_INCOMPATIBLEEXTVERSION
The caller requested an extension version or a version range that cannot be supported by the service provider.
PHONEERR_INIFILECORRUPT
The telephon.ini file was corrupted.
PHONEERR_INUSE
The device is currently in use, or the phone device is in use and cannot currently be configured.
PHONEERR_INVALBUTTONLAMPID
The specified button identifier is out of range, invalid, or not supported by the service provider or phone.
PHONEERR_INVALBUTTONMODE
The button mode parameter is invalid.
PHONEERR_INVALBUTTONSTATE
The button states parameter is invalid.
PHONEERR_INVALDATAID
The specified data identifier is invalid or the number of bytes specified in dwSize cannot be read from that location.
PHONEERR_INVALDEVICECLASS
The service provider or phone does not support the indicated device class.
PHONEERR_INVALHOOKSWITCHDEV
The hookswitch device parameter is invalid or not supported by the phone or service provider.
PHONEERR_INVALLAMPMODE
The specified lamp mode parameter is invalid or not supported by the phone or service provider.
PHONEERR_INVALPARAM
The row or column parameters or window handle parameter are invalid or out of range.
PHONEERR_INVALPHONEHANDLE
The specified device handle, such as hdPhone, is invalid.
PHONEERR_INVALPHONESTATE
The phone device is not in a valid state for the requested operation, or the specified phone states parameter is invalid.
PHONEERR_INVALPOINTER
The specified pointer parameter is invalid.
PHONEERR_INVALRINGMODE
The ring mode parameter is invalid or not supported by the phone or service provider.
PHONEERR_NODRIVER
This error can be returned from a function when the driver finds that one of its components is corrupt in a way that was not detected at initialization. For example, if a service provider consists of multiple components such as a Virtual Device Driver (VxD) in addition to the usual DLL (exporting the TSPI interface and having the .TSP extension), PHONEERR_NODRIVER can be returned to indicate that the VxD component was missing.
PHONEERR_NOMEM
Unable to allocate or lock memory.
PHONEERR_OPERATIONFAILED
The operation failed for unspecified reasons.
PHONEERR_OPERATIONUNAVAIL
The operation is not available.
PHONEERR_RESOURCEUNAVAIL
There are not enough resources available to complete the request.

The values 0xC0000000 through 0xFFFFFFFF are available for device-specific extensions, the values 0x80000000 through 0xBFFFFFFF are reserved, and 0x00000000 through 0x7FFFFFFF are used as request identifiers.


PHONEHOOKSWITCHDEV_ Constants

The PHONEHOOKSWITCHDEV_ bit-flag constants describe various audio I/O devices, each with its own hookswitch that is controllable from the computer.

PHONEHOOKSWITCHDEV_HANDSET
The ubiquitous, hand-held ear- and mouthpiece.
PHONEHOOKSWITCHDEV_SPEAKER
A built-in loudspeaker and microphone. This could also be an externally connected adjunct speaker to the telephone set.
PHONEHOOKSWITCHDEV_HEADSET
A headset connected to the phone set.

Not extensible. All 32 bits are reserved.

These constants are used in the PHONECAPS data structure to indicate the hookswitch device capabilities of a phone device. The PHONESTATUS structure reports the state of the phone's hookswitch devices. The functions TSPI_phoneSetHookSwitch and TSPI_phoneGetHookSwitch use it as a parameter to select the phone's I/O device.

See Also

PHONECAPS, PHONESTATUS, TSPI_phoneGetDevCaps, TSPI_phoneGetHookSwitch, TSPI_phoneGetStatus, TSPI_phoneSetHookSwitch


PHONEHOOKSWITCHMODE_ Constants

The PHONEHOOKSWITCHMODE_ bit-flag constants describe the microphone and speaker components of a hookswitch device.

PHONEHOOKSWITCHMODE_ONHOOK
The device's microphone and speaker are both onhook.
PHONEHOOKSWITCHMODE_MIC
The devicer's microphone is active, the speaker is mute.
PHONEHOOKSWITCHMODE_SPEAKER
The device's speaker is active, the microphone is mute.
PHONEHOOKSWITCHMODE_MICSPEAKER
The device's microphone and speaker are both active.
PHONEHOOKSWITCHMODE_UNKNOWN
The device's hookswitch mode is currently unknown.

Not extensible. All 32 bits are reserved.

These constants are used to provide an individual level of control over the microphone and speaker components of a phone device.

See Also

PHONECAPS, PHONESTATUS, TSPI_phoneGetDevCaps, TSPI_phoneGetHookSwitch, TSPI_phoneGetStatus, TSPI_phoneSetHookSwitch


PHONELAMPMODE_ Constants

The PHONELAMPMODE_ bit-flag constants describe various ways in which a phone's lamp can be lit.

PHONELAMPMODE_DUMMY
This value is used to describe a button/lamp position that has no corresponding lamp.
PHONELAMPMODE_OFF
The lamp is off.
PHONELAMPMODE_STEADY
The lamp is continuously lit.
PHONELAMPMODE_WINK
Wink means normal rate on and off.
PHONELAMPMODE_FLASH
Flash means slow on and off.
PHONELAMPMODE_FLUTTER
Flutter means fast on and off.
PHONELAMPMODE_BROKENFLUTTER
Broken flutter is the superposition of flash and flutter.
PHONELAMPMODE_UNKNOWN
The lamp mode is currently unknown.

The high-order 16 bits can be assigned for device-specific extensions. The low-order 16 bits are reserved.

Where the exact on and off cadences can differ across phone sets from different vendors, mapping of actual lamp lighting patterns for most phones onto the values listed above should be straightforward.

See Also

PHONECAPS, PHONESTATUS, TSPI_phoneGetDevCaps, TSPI_phoneGetLamp, TSPI_phoneGetStatus, TSPI_phoneSetLamp


PHONESTATE_ Constants

The PHONESTATE_ bit-flag constants describe various status items for a phone device.

PHONESTATE_OTHER
A phone status information item other than those listed below has changed.
PHONESTATE_CONNECTED
The connection between the phone device and TAPI was just made. This happens when TAPI is first invoked, or when the wire connecting the phone to the computer is plugged in with TAPI active.
PHONESTATE_DISCONNECTED
The connection between the phone device and TAPI was just broken. This happens when the wire connecting the phone set to the computer is unplugged while TAPI is active.
PHONESTATE_OWNER
The number of owners for the phone device.
PHONESTATE_MONITORS
The number of monitors for the phone device.
PHONESTATE_DISPLAY
The display of the phone has changed.
PHONESTATE_LAMP
A lamp of the phone has changed.
PHONESTATE_RINGMODE
The ring mode of the phone has changed.
PHONESTATE_RINGVOLUME
The ring volume of the phone has changed.
PHONESTATE_HANDSETHOOKSWITCH
The handset hookswitch state has changed.
PHONESTATE_HANDSETVOLUME
The handset's speaker volume setting has changed.
PHONESTATE_HANDSETGAIN
The handset's microphone gain setting has changed.
PHONESTATE_SPEAKERHOOKSWITCH
The speakerphone's hookswitch state has changed.
PHONESTATE_SPEAKERVOLUME
The speakerphone's speaker volume setting has changed.
PHONESTATE_SPEAKERGAIN
The speakerphone's microphone gain setting state has changed.
PHONESTATE_HEADSETHOOKSWITCH
The headset's hookswitch state has changed.
PHONESTATE_HEADSETVOLUME
The headset's speaker volume setting has changed.
PHONESTATE_HEADSETGAIN
The headset's microphone gain setting has changed.
PHONESTATE_SUSPEND
The application's use of the phone is temporarily suspended.
PHONESTATE_RESUME
The application's use of the phone device is resumed after having been suspended for some time.
PHONESTATE_DEVSPECIFIC
The phone's device-specific information has changed.
PHONESTATE_REINIT
Items have changed in the configuration of phone devices. To become aware of these changes (as for the appearance of new phone devices) the application should reinitialize its use of TAPI.

Not extensible. All 32 bits are reserved.

See Also

PHONE_STATE, PHONESTATUS, TSPI_phoneSetStatusMessages


PHONESTATUSFLAGS_ Constants

The PHONESTATUSFLAGS_ bit-flag constants describe phone device status information.

PHONESTATUSFLAGS_CONNECTED
Specifies whether the phone is currently connected to TAPI. TRUE if connected, FALSE otherwise.
PHONESTATUSFLAGS_SUSPENDED
Specifies whether TAPI's manipulation of the phone device is suspended. TRUE if suspended, FALSE otherwise. An application's use of a phone device may be temporarily suspended when the switch wants to manipulate the phone in a way that cannot tolerate interference from the application.

Not extensible. All 32 bits are reserved.

See Also

PHONESTATUS


STRINGFORMAT_ Constants

The STRINGFORMAT_ enumeration constants describe different string formats.

STRINGFORMAT_ASCII
Specifies standard ASCII character format using one byte per character.
STRINGFORMAT_DBCS
Specifies standard DBCS character format using two bytes per character.
STRINGFORMAT_UNICODE
Specifies standard Unicode character format using two bytes per character.
STRINGFORMAT_BINARY
This is an array of unsigned characters; could be used for numeric values.

Not extensible. All 32 bits are reserved.

See Also

VARSTRING


TUISPIDLL_OBJECT_

TUISPIDLL_OBJECT_LINEID 0x00000001
TUISPIDLL_OBJECT_PHONEID 0x00000002
TUISPIDLL_OBJECT_PROVIDERID 0x00000003
TUISPIDLL_OBJECT_DIALOGINSTANCE 0x00000004

Parameters

TUISPIDLL_OBJECT_LINEID
dwObjectID is a line device identifier (dwDeviceID).
TUISPIDLL_OBJECT_PHONEID
dwObjectID is a phone device identifier (dwDeviceID).
TUISPIDLL_OBJECT_PROVIDERID
dwObjectID is a permament provider identifier.
TUISPIDLL_OBJECT_DIALOGINSTANCE

dwObjectID is a dialog instance handle (either HDRVDIALOGINSTANCE or HTAPIDIALOGINSTANCE, depending on the context).


TSPI Device Classes

A device class is a group of related physical devices or device drivers through which applications send and receive the information or data that makes up a call. Every device class has a device class name that uniquely identifies the class and provides information about the programming interface and commands that can be used to open and communicate with the devices in the class.

The Telephony Application Programming Interface (TAPI) associates devices from one or more device classes to each line or phone device. You access one of these devices by retrieving the device identifier for the device using the lineGetID or phoneGetID function. You supply the device class name, and the function returns the specific port name, device name, device handle, or device identifier that you need to open and access the device. The format of the returned information depends on the device class and is described in this section.

Note The device identifier definitions apply to 16-bit and 32-bit TAPI. In some cases, the datatype of a media handle in the device identifier definition may be different from that specified by the Microsoft Windows version 3.x or Microsoft Win32 application programming interface (API). For example, Windows 3.x and Win32 define wave device identifiers with the UINT type, but TAPI defines this device identifier with the DWORD type. In such cases, you cast the media handle to the appropriate datatype when using it with the Windows version 3.x or Win32 API.

You also use device class names with the lineConfigDialog and phoneConfigDialog functions to enable the user to set configuration options for the given device; with the lineGetIcon and phoneGetIcon functions to retrieve an icon to represent the given device; and with the lineGetDevConfig and lineSetDevConfig functions to directly retrieve and set configuration options for the given device.

Following are the default device class names.

Device Class Name | Description
comm | Communications port
comm/datamodem | Modem through a communications port
comm/datamodem/portname | Name of the device to which a modem is connected
wave/in | Wave audio device (input only)
wave/out | Wave audio device (output only)
midi/in | Midi sequencer (input only)
midi/out | Midi sequencer (output only)
tapi/line | Line device
tapi/phone | Phone device
ndis | Network device
tapi/terminal | Terminal device

These names are not case sensitive, so you can use any combination of uppercase and lowercase letters.

Additional device classes and device class names may be available on a given system. In general, if a device does not belong to one of the default device classes, the manufacturer typically defines a new device class and assigns a unique device class name. You must check the documentation for the device to determine what additional device classes are available for it. Note, however, that although the device class and media mode are related, they are not the same. A media mode describes a format of information on a call, and a device class defines the programming interface used to manage that information. So, even if a manufacturer defines a new media mode, it may not be true that the manufacturer must also define a new device class to support the mode.

The format of the configuration data used with the lineSetDevConfig and lineGetDevConfig functions also depends on the device class. In general, you use lineGetDevConfig to save a copy of the current device configuration data and then later use lineSetDevConfig with the saved configuration data to restore the device configuration to the previous state. This is a convenient way to temporarily change the configuration without requiring the user to manually restore it to the previous state. Because the exact format of the device configuration data may be different with each service provider, do not use lineSetDevConfig and lineGetDevConfig to manipulate the device configuration data directly. Some formats are provided for information only.


comm

The comm device class consists of communications ports. You access these devices using the Win32 file and communications functions.

The lineGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_ASCII value and appending a NULL-terminated string that specifies the name of the communication device (such as the modem name).


comm/datamodem

The comm/datamodem device class consists of data modem devices. You access these devices using the Win32 file and communications functions. Devices in this class are associated with line devices that support the LINEMEDIAMODE_DATAMODEM media mode, which is specified in the dwMediaModes member of the LINEDEVCAPS structure for the line device.

The lineGetID function fills a VARSTRING structure, setting dwStringFormat to the STRINGFORMAT_BINARY value and appending these additional members:

HANDLE hComm;            // Win32 file handle to data modem
CHAR   szDeviceName[1];  // name of data modem

The hComm member is the handle of the open communications port. This member is NULL if the port is not yet open or if the dwSelect parameter of lineGetID is not the LINECALLSELECT_CALL value. The service provider is responsible for duplicating the handle into the calling process's context, as specified by the hTargetProcess parameter. If a call is active, the service provider typically opens the port itself to get direct control of the communications hardware, but is only required to return a valid handle if the line is connected. The service provider opens the port using the FILE_FLAG_OVERLAPPED value, and then configures the port using the settings specified by the lineSetDevConfig function. An application can set additional configuration options for the device using Win32 functions with the returned handle.

The szDeviceName member is a NULL-terminated ASCII string that specifies the name of the communications port associated with the line, address, or call.

When using the lineGetDevConfig and lineSetDevConfig functions, some service providers require that the configuration data for this device class have the following format:

typedef struct  tagDEVCFG  {
    DEVCFGHDR   dfgHdr;
    COMMCONFIG  commconfig;
} DEVCFG, *PDEVCFG, FAR* LPDEVCFG;

// Device setting information
typedef struct  tagDEVCFGDR  {
    DWORD       dwSize;
    DWORD       dwVersion;
    WORD        fwOptions;
    WORD        wWaitBong;
} DEVCFGHDR;

Contains device configuration information for use with the TSPI_lineGetDevConfig and TSPI_lineSetDevConfig functions.

DwSize
Sum of the size of the DEVCFGHDR structure and the actual size of COMMCONFIG structure.
DwVersion
Version number of the Unimodem DevConfig structure. This member can be MDMCFG_VERSION (0x00010003).
FwOptions
Option flags that appear on the Unimodem Option page. This member can be a combination of these values:
TERMINAL_PRE (1)
Displays the preterminal screen.
TERMINAL_POST (2)
Displays the post terminal screen.
MANUAL_DIAL (4)
Dials the phone manually, if capable of doing so.
LAUNCH_LIGHTS (8)
Displays the modem tray icon.

Only the LAUNCH_LIGHTS value is set by default.

WWaitBong
Number of seconds (in two seconds granularity) to replace the wait for credit tone ($).
Commconfig
COMMCONFIG structure that can be used with the Win32 communications and MCX functions.


comm/datamodem/portname

The comm/datamodem/portname device class consists of the device names to which modems are attached. When this device name is specified in a call to the TSPI_lineGetID function, the service provider fills the VARSTRING structure with a NULL-terminated ANSI (not Unicode) string specifying the name of the port to which the specified modem is attached, such as "COM1\0". This is intended primarily for identification purposes in the user interface, but could be used under some circumstances to open the device directly, bypassing the service provider (if the service provider does not already have the device open itself). If there is no port associated with the device, a NULL string ("\0") is returned in the VARSTRING structure (with a string length of 1).


wave/in

The wave/in device class consists of audio devices for low-level wave audio input. You access these devices using the wave functions, which are described in the Microsoft Platform Software Development Kit. Devices in this class are associated with line devices that support the LINEMEDIAMODE_AUTOMATEDVOICE media modem which is specified in the dwMediaModes member of the LINEDEVCAPS structure for the line device.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD DeviceId;  // identifier of audio device

The DeviceId member is the identifier of a closed audio device. You use this identifier in a call to the waveInOpen function to open the device for input. You can use the resulting device handle to record digitized audio data from the line or phone device.

Although a wave device class also exists for low-level wave audio devices, you should always use the wave/in device class for low-level wave input.


wave/out

The wave/out device class consists of audio devices for low-level wave audio output. You access these devices by using the wave functions, which are described in the Microsoft Platform SDK. Devices in this class are associated with line devices that support the LINEMEDIAMODE_AUTOMATEDVOICE media mode, which is specified in the dwMediaModes member of the LINEDEVCAPS structure for the line device.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD DeviceId;  // identifier of audio device

The DeviceId member is the identifier of a closed audio device. You use this identifier in a call to the waveOutOpen function to open the device for output. You can use the resulting device handle to play digitized audio data at the line or phone device.

Although a wave device class also exists for low-level wave audio devices, you should always use the wave/out device class for low-level wave output.


midi/in

The midi/in device class consists of MIDI sequencers that are used for input. You access these devices using the MIDI functions, which are described in the Microsoft Platform SDK.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD DeviceId;  // identifier of MIDI device

The DeviceId member is the identifier of a closed MIDI device. You use this identifier in a call to the midiInOpen function to open the device for input. You can use the resulting device handle to record MIDI data from the line or phone device.


midi/out

The midi/out device class consists of MIDI sequencers that are used for output. You access these devices by using the MIDI functions, which are described in the Microsoft Platform SDK.

The lineGetID and phoneGetID functions fill a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD DeviceId;  // identifier of MIDI device

The DeviceId member is the identifier of a closed MIDI device. You use this identifier in a call to the midiOutOpen function to open the device for output. You can use the resulting device handle to play MIDI data at the line or phone device.


tapi/line

The tapi/line device class consists of all line devices. You access these devices using the TAPI line functions.

The lineGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD dwDeviceI;  // line device identifier

The dwDeviceId member is the identifier of the line device associated with the line handle given by lineGetID.

The phoneGetID function also fills a VARSTRING structure, setting dwStringFormat to STRINGFORMAT_BINARY and appending this additional member:

DWORD adwDeviceIds[];  // array of line device identifiers

The adwDeviceIds member is an array containing the device identifiers of all line devices that are associated with the phone device. If there are no associated line devices, phoneGetID returns the PHONEERR_INVALDEVICECLASS value.


tapi/phone

The tapi/phone device class consists of all phone devices. You access these devices using the TAPI phone functions.

The phoneGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD dwDeviceI;  // phone device identifier

The dwDeviceId member is the identifier of the phone device associated with the phone handle given by phoneGetID.

The lineGetID function also fills a VARSTRING structure, setting dwStringFormat to STRINGFORMAT_BINARY and appending this additional member:

DWORD adwDeviceIds[];  // array of phone device identifiers

The adwDeviceIds member is an array containing the device identifiers of all phone devices that are associated with the given line device. If there are no associated phone devices, lineGetID returns the LINEERR_INVALDEVICECLASS value.


ndis

The ndis device class consists of devices that can be associated with network driver interface specification (NDIS) media access control (MAC) drivers to support network communications. You access these devices by using functions.

The lineGetID and phoneGetID functions fill a VARSTRINGstructure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending these additional members:

HANDLE  hDevice;          // NDIS connection identifier
    CHAR    szDeviceType[1];  // name of device

The hDevice member is the identifier to pass to a MAC, such as the asynchronous MAC for dial-up networking, to associate a network connection with the call/modem connection. The szDeviceType member is a NULL-terminated ASCII string specifying the name of the device associated with the identifier. For more information, refer to documentation about writing NDIS MAC drivers for use with dial-up networking.


tapi/terminal

The tapi/terminal device class consists of the phone devices associated with each terminal on a line or the terminal on each line associated with a phone device. You access these devices by using the TAPI line or phone functions.

The lineGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD adwDeviceId[];  // array of phone device identifiers

The adwDeviceId member is an array of phone device identifiers. There is one array element for each terminal specified by the dwNumTerminals member in the LINEDEVCAPS structure for the given line device. Each element specifies the identifier of the phone device associated with the corresponding terminal on the line. If there is no phone device associated with a terminal, the element is set to –1 (0xFFFFFFFF).

The phoneGetID function fills a VARSTRING structure, setting the dwStringFormat member to the STRINGFORMAT_BINARY value and appending this additional member:

DWORD adwTerminalID[];  // array of terminal identifiers

The adwTerminalID member is an array of terminal identifiers. There is one array element for each line device identifier specified by the lineInitialize function. Each array element contains the terminal identifier associated with the phone device for the given line device. If there is no phone device, the element is set to –1 (0xFFFFFFFF). The terminal identifiers range in value from zero to one less than the number specified by the dwNumTerminals member in the LINEDEVCAPS structure.


TSPI Service Provider Datatypes

This section contains a list of the service provider datatypes in the Telephony SPI.


DRV_REQUESTID

The DRV_REQUESTID datatype is used to supply a unique identifier for a request to the service provider. A value of this type is passed as a parameter to every function that allows for asynchronous operation. If the operation is asynchronous, the service provider returns this value as the return value of the function. Whenever the service provider flags a request as asynchronous in this way, it must eventually report the operation is complete by calling the ASYNC_COMPLETION callback function.

TAPI ensures that the DRV_REQUESTID values it supplies are strictly positive, that is, between the values of 0x00000001 and 0x7FFFFFFF, inclusive. Furthermore, the values are unique in that no value returned from a function to flag the request as asynchronous will be re-used before the operation is reported complete.


HDRVCALL

The HDRVCALL datatype represents a service provider's opaque handle for a call data structure. The service provider must resolve a value of this type into a reference to the appropriate data structure instance.


HDRVLINE

The HDRVLINE datatype represents a service provider's opaque handle for a line data structure. The service provider must resolve a value of this type into a reference to the appropriate data structure instance.


HDRVPHONE

The HDRVPHONE datatype represents a service provider's opaque handle for a phone data structure. The service provider must resolve a value of this type into a reference to the appropriate data structure instance.


HTAPICALL

The HTAPICALL datatype represents the TAPI opaque handle for a call data structure. TAPI must resolve a value of this type into a reference to the appropriate data structure instance. The service provider must not attempt to reference through this as if it were a pointer, make assumptions about its values, or interpret its representation in any way other than passing its value to TAPI at appropriate times.


HTAPILINE

The HTAPILINE datatype represents the TAPI opaque handle for a line data structure. TAPI must resolve a value of this type into a reference to the appropriate data structure instance. The service provider must not attempt to reference through this as if it were a pointer, make assumptions about its values, or interpret its representation in any way other than passing its value to TAPI at appropriate times.


HTAPIPHONE

The HTAPIPHONE datatype represents TAPI's opaque handle for a phone data structure. TAPI must resolve a value of this type into a reference to the appropriate data structure instance. The service provider must not attempt to reference through this as if it were a pointer, make assumptions about its values, or interpret its representation in any way other than passing its value to TAPI at appropriate times.


INITIALIZE_NEGOTIATION

The INITIALIZE_NEGOTIATION datatype is a special value of type DWORD. It can be passed as the dwDeviceID parameter in the TSPI_lineNegotiateTSPIVersion and TSPI_phoneNegotiateTSPIVersion functions. Doing so indicates that TAPI can negotiate a TSPI interface version number independent of any specific devices.


TSPIMessage

TSPIMessage is an enumeration type that defines the set of additional LINEEVENT and PHONEEVENT functions appearing in TSPI that do not appear in TAPI.

Parameters

TSPI_MESSAGE_BASE
The lowest number in the range of TSPI-specific message values. This value has no meaning by itself, but serves as a base for defining the other values.
LINE_NEWCALL
Specifies that a new, incoming call has arrived and introduces it to TAPI. This must be the first message sent to TAPI for a new incoming call. TAPI returns its opaque identifier for the call as part of its handling of this message.
LINE_CALLDEVSPECIFIC
Specifies that a device-specific event has occurred on a call device.
LINE_CALLDEVSPECIFICFEATURE
Specifies that a device-specific feature event has occurred on a call device.


Legal Information

[This is preliminary documentation and subject to change.]

Telephony Application Programming Interface (TAPI) Version 3.0 Programmer's Reference

This is a preliminary document and may be changed substantially prior to final commercial release. This document is provided for informational purposes only and Microsoft Corporation makes no warranties, either express or implied, in this document. The entire risk of the use or the results of the use of this document remains with the user. The names of companies, products, people, characters, and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted. Complying with all applicable copyright laws is the responsibility of the user. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Microsoft Corporation. If, however, your only means of access is electronic, permission to print one copy is hereby granted.

Portions of this document specify and accompany software that is still in development. Some of the information in this documentation may be inaccurate or may not be an accurate representation of the functionality of final documentation or software. Microsoft assumes no responsibility for any damages that might occur directly or indirectly from these inaccuracies.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 1995-1998 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, MS, Windows, Windows NT, Win32, DirectShow, and Visual Basic are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries.

Other product and company names mentioned herein may be the trademarks of their respective owners.


About TAPI Version 3.0

[This is preliminary documentation and subject to change.]

Version 3.0 of the Telephony Application Programming Interface (TAPI) is based on the Component Object Model (COM) and uses DirectShow™ filters to provide access to the media. Developers who are not familiar with COM or DirectShow should consult the relevant Platform SDK sections. Those who are not familiar with telephony should read the overview sections of the TAPI version 2.1 material in the Platform SDK.

TAPI 3.0 does not replace TAPI 2.1 or make it obsolete. Microsoft continues to support and develop TAPI 2.1.

TAPI Version 3.0

  • TAPI Version 3.0 General Description
  • What's New with TAPI Version 3.0
  • TAPI Version 3.0 Requirements

Call And Media Controls

  • About Call And Media Controls
  • Using Call And Media Controls
  • Call and Media Control Code Fragments
  • Call and Media Control Reference

Rendezvous Controls for IP Conferencing

  • About Rendezvous
  • Rendezvous Code Fragments
  • Rendezvous Reference

DirectShow Real-Time Transport Protocol

  • About DirectShow Real-Time Transport Protocol
  • Using DirectShow Real-Time Transport Protocol
  • DirectShow Real-Time Transport Protocol Reference


TAPI Version 3.0 General Description

[This is preliminary documentation and subject to change.]

TAPI version 3.0 is a set of COM-based APIs providing convergence of both traditional telephony and IP (Internet Protocol) Telephony.

IP Telephony enables voice, data and video collaboration over existing LANs, WANs and the Internet. TAPI 3.0 implements IP Telephony on the Windows® platforms by providing simple and generic methods for making connections between two or more machines.

TAPI 3.0 supports standards-based H.323 conferencing and IP Multicast conferencing, utilizing the Windows NT® 5.0 Active Directory service to simplify deployment within an organization. Quality-of-service (QOS) support is included to improve conference quality and network manageability. Media stream access is provided through DirectShow® filters.

TAPI 3.0 PSTN and IP functionality is provided by three main sections: call and media controls, media stream controls, and directory controls. The following diagram illustrates how these controls interact with the telephone and IP networks.

The beta 1 release of TAPI 3.0 contains the core elements of telephony. Future releases will include interfaces and objects to expose and encapsulate additional telephony concepts, including call center-specific functionality.


What's New with TAPI Version 3.0

[This is preliminary documentation and subject to change.]

  • Component Object Model (COM) architecture. Evolving TAPI into COM allows the creation of applications that can be maintained and upgraded by function rather than as .EXE files. COM is also language-neutral, permitting developers to write TAPI enabled applications in any language, such as Java, Visual Basic®, or C/C++. Note that some interface methods may not be available to scripting languages such as VB Script.
  • Media stream access by means of DirectShow (formerly ActiveMovie™). Media-stream access allows applications to process a diverse range of media and to respond precisely to changes in the media stream.
  • Integration with Windows NT® 5.0 ActiveDirectory.
  • Supports H.323 protocols with IP Telephony Service Provider.
  • Supports MBone protocols with IP Multicast conferencing service provider.
  • Integrates Quality of Service (QOS).


TAPI Version 3.0 Requirements

[This is preliminary documentation and subject to change.]

TAPI version 3.0 basic call controls operate with Windows® 95 or any version of Windows NT® later than 3.5.

Media stream control using the Real-Time Transport Protocol DirectShow™ filters requires Windows NT version 5.0 or later. The DirectShow filters needed are part of Windows NT 5.0 and do not require special installation.

Directory control using Rendezvous for IP Conferencing requires that an ILS server be in place and that the end user has a means of entering the network name of the server.

Two new Telephony Service Providers (TSPs) for IP Telephony and conferences are included with Windows NT 5.0. These can be configured either manually by the end user or programmatically by an application. (See lineAddProvider in the TAPI version 2.1 reference section.)


About Call And Media Controls

[This is preliminary documentation and subject to change.]

Call and media controls are a simple and generic set of methods for making calls between two or more machines. In the context of TAPI 3.0, the word call refers not just to voice transmission over the public switched telephone network (PSTN) but to any medium capable of transferring content.

TAPI 3.0 provides access to the media being transmitted through the use of DirectShow™. DirectShow is a modular system of pluggable components called filters, arranged in a configuration called a filter graph. The filter graph manager oversees the connection of these filters and controls the stream's data flow.

TAPI 3.0 abstracts both call and media functionality to allow different, and seemingly incompatible, communication protocols to expose a common interface to applications. Because TAPI 3.0 is based on the Component Object Model (COM), applications may be written in any language. Some interface methods may not be available to scripting languages such as VBScript.

TAPI 3.0 call and media controls involve four primary sets of code: the TAPI 3.0 COM objects, the TAPI Server, Telephony Service Providers (TSPs), and Media Service Providers (MSPs).

TAPI 3.0 COM Object

TAPI 3.0 COM objects are described in Using Call And Media Controls and detailed in Call and Media Control Reference.

TAPI Server

TAPI 3.0 is implemented as an in-process server and uses TAPISRV.EXE to perform telephony operations, thus making TAPI 3.0 applications compatible with all TAPI 2.1 service providers. The TAPI Server process (TAPISRV.EXE) abstracts TSPI (Telephony Service Provider Interface) from TAPI 3.0 and TAPI 2.1 and maintains the internal state of TAPI.

Additional information concerning the TAPI Server and TSPI can be found in the Platform SDK under "Telephony" or by conducting a search.

Call Control Functions

Call-control functions are provided by a TSP. The TAPI 2.1 client/server relationship with remote services providers is supported. Telephony Service Providers are responsible for translating the protocol-independent call model of TAPI into protocol-specific call setup and teardown, on a service-by-service basis. TAPI 3.0 has backward compatibility with TAPI 2.1 TSPs. Two new IP Telephony Service Providers (and their associated Media Service Providers) ship by default with TAPI 3.0: the H.323 TSP and the IP Multicast Conferencing TSP.

Additional information concerning Telephony Service Providers can be found in the Platform SDK under "Telephony" or by conducting a search,

Media control functions

Media control functions are provided by an MSP that implements the DirectShow interfaces for a particular provider. Media Service Providers are required for any telephony service that makes use of DirectShow media streaming. Generic streams are handled by the application.

TAPI service providers are strongly encouraged to support DirectShow. A service provider does not have to support DirectShow for all media. For example, a PBX implementation may only offer call control through TAPI 3.0, but not media -stream access.


DirectShow Media Handling

[This is preliminary documentation and subject to change.]

One of the main goals for TAPI version 3.0 is to provide a uniform way to access the media streams or data of a call. In this context, "stream" does not refer to the traditional use as in "streaming" but simply to the data or media. TAPI 3.0 has been designed to support DirectShow™ as the primary processor for media. Additionally, there is support for accessing raw data.

TAPI 3.0 provides very high-level abstraction of media streams (see Media Type for definitions). Additional media types can be registered so that providers can expose their own data types.

A TAPI 3.0 application typically specifies a terminal to use with a media type. The combination of a terminal and a media type forms a ITMediaTerminal object. When a call is made, the application specifies an array of ITMediaTerminals used when creating and connecting the call. This allows an application to be very specific about call set-up. For example, the audio portion of the call can be rendered through the soundcard and recorded to a file.

Any DirectShow renderer can be a TAPI 3.0 terminal. If a DirectShow filter exists that can handle the input, a TAPI application can direct the media flow to it. The terminal can be a soundcard, a video display, a file, or a device yet to be invented.

An application can also specify NULL for the ppTerminal member of the ITMediaTerminal object. This is only valid for a DirectShow MEDIATYPE, and indicates that the application can handle the DirectShow filter graph after the call is set up. TAPI 3.0 then sets up the smallest possible DirectShow filtergraph for the specified MediaType. TAPI assumes the application takes responsibility after the call is connected.

On return of the call, the application may choose to access the DirectShow filter graph that may have been set up for the call. The actual instantiation of the filters is handled by the media service provider which is called implicitly by Connect. The application can modify the filter graph but the graph might not be ready to play until the call is in a connected state.

The handling of generic data streaming will be defined in an upcoming version of TAPI.

DirectShow filters developed for use with TAPI 3.0 are covered in About DirectShow Real-Time Transport Protocol. The filters include methods for specifying Quality of Service (QOS).


Provider-Specific Interfaces

[This is preliminary documentation and subject to change.]

TAPI service providers may provide additional interfaces through TAPI 3.0 objects to implement provider-specific features.

The provider-specific interfaces should be optional and intended for applications written with a specific provider in mind. An application must be able to make connections and access standard media streams without using the provider-specific interfaces.

For TAPI 3.0, raw data streams should be exposed through provider specific interfaces.


Using Call And Media Controls

[This is preliminary documentation and subject to change.]

This section describes how to use the TAPI version 3.0 Component Object Model (COM) objects, interfaces, and methods for information transfer. familiarity with COM and DirectShow™ is assumed. If you require additional information about COM or DirectShow, please consult the Platform SDK.

Call and Media Control Component Objects

There are five main objects in the TAPI 3.0 call and media control architecture: TAPI, Address, Terminal, Call, and CallHub. The following diagram shows these objects, along with their associated interfaces. The outgoing interfaces are denoted with an italic font. Some interfaces are stand-alone objects and are not shown in this diagram. See Call and Media Control COM Interfacesfor a list of all interfaces.

Call-center functionality is not implemented for Windows NT® 5 beta 1.


TAPI Object

[This is preliminary documentation and subject to change.]

The TAPI object is the application's entry point to TAPI 3.0. A TAPI 3.0 application must first create an instance of the TAPI server object before initializing it. This object represents all telephony resources to which the local computer has access, allowing an application to enumerate all local and remote addresses. Remote addresses may be distributed across multiple servers.


Address Object

[This is preliminary documentation and subject to change.]

An address object represents the origination or destination point for a call. Capabilities can be retrieved from an address object, such as media and terminal support. An application can wait for a call on an address object, or can create an outgoing call object from an address object.

The address object maps closely to "address" as used in earlier versions of TAPI.


Terminal Object

[This is preliminary documentation and subject to change.]

A terminal object represents the sink or renderer at the termination or origination point of a connection. The terminal object can map to hardware used for human interaction, such as a telephone or microphone, but can also be a file or any other device capable of receiving input or creating output.

A terminal object allows the user to select the devices used and perhaps to provide a common way to control them (such as audio or video controls). If the application does not want TAPI 3.0 to set up the terminal (or sink), it has the option of not specifying a terminal. This is only applicable if one or more media streams used during the call are set up with DirectShow. In that case, the application is responsible for handling any terminal issues.

Each terminal belongs to a terminal class. A terminal class represents a specific type of terminal, such as a handset or soundcard. TAPI 3.0 defines certain terminal classes, and new terminal classes can be registered. Defined terminal classes include handset, headset, soundcard, monitor, camera, and file. See Terminal Classes for current definitions. Each terminal class is assigned a globally unique identifier (GUID).

Terminal classes can be either STATIC or DYNAMIC. A STATIC terminal usually corresponds to hardware – a single device that already exists, and cannot be created "on the fly". A DYNAMIC terminal represents a terminal that can be created, such as a file or a network connection.

Terminals support DirectShow by default. The IsStandardTerminal method of the ITTerminal interface can be used to determine if the terminal supports DirectShow. A non-standard terminal with no DirectShow support cannot manipulate the media stream from TAPI 3.0.

TAPI 3.0 defines a base audio terminal interface and a base video terminal interface. These interfaces have core methods, such as put_Volume, to control the terminal. Applications using DirectShow may control the terminal directly through the DirectShow interfaces.

If the application does not select a default terminal device for each media type it supports, TAPI 3.0 can select one.


Call Object

[This is preliminary documentation and subject to change.]

The call object represents an address's connection between the local address and one or more other addresses. The following diagram represents a two-person phone call. The call objects are pCallA and pCallB , and the call hub is pCallHub. Users are represented as A and B.

All call control is done through the call object. You can think of the call object as a first party view of the telephone call. Using the CallHub object, a user with the required security can discover and potentially control other participants in a call. For example, in the earlier picture, user A's application uses pCallA to do all call control, and user B's application uses pCallB to do all call control. A's application can use the pCallHub to get pCallB. A's application can use pCallB to discover information about B. If A has been granted sufficient rights, A's application can also use pCallB to perform call control from B's point of view.

To make a call, an application selects an address object, then invokes the CreateCall method as shown in the following code fragment:

pAddress->CreateCall(pszDestAddress,
                         &pCall);
    pCall->SelectMediaTerminals(…);
    pCall->Connect(TRUE);

After Connect is called, the call has been started. At this point, the application can retrieve the CallHub object to find the other associated call objects. The following code fragment demonstrates the method calls.

pCall->QueryInterface(IID_ITCallInfo,
                          &pCallInfo);
    pCallInfo->get_CallHub(&pCallHub);
    pCallHub->_EnumerateCalls(&pEnumCalls);

Note The application's own pCall is included when _EnumerateCalls is invoked.


CallHub Object

Call-center functionality is not implemented for Windows® NT 5 beta 1.

[This is preliminary documentation and subject to change.]

The CallHub object represents a set of related calls, as described earlier in Call Object .

A CallHub object cannot be created directly by an application. A CallHub object is created indirectly when an incoming call is received through TAPI 3.0. as in the preceding code fragment for Call Object.

When an application must monitor calls, it can do so either through the CallHub registering the ITCallHubEventNotification interface on the TAPI object, or through the Call objects by registering the ITCallNotification interface on the Address object.

CallHub Limitations

TAPI 3.0 relies on TAPI service providers to provide the necessary information about calls to implement the CallHub object. Since not all service providers provide this information, and not all hardware supports such tracking, the information available about the other users in the connection may be limited or non-existent.


Conferencing

[This is preliminary documentation and subject to change.]

The following material describes the basic steps for conference calling using TAPI 3.0.

Creating a Conference

Joining a Conference

Transferring

Developers interested in writing IP multicast conferencing applications should also consult About Rendezvous.


Creating a Conference

[This is preliminary documentation and subject to change.]

The method for setting up a conference is as follows:

A call exists between two parties, as in the diagram below.

User A decides to add another party to the conference. The application calls:

pCallA->AddToConference(pszDestAddress,
                           TRUE,
                           &pConsultCallA);

This creates a CallHub object for consultation, as shown in the following diagram:

User A may then use the ITConsultCall interface to discover whether private interaction is possible with user C.

pConsultCallA->CanIConsult( pbConsultC );

If CanIConsult returns pbConsultC as TRUE and user A would like to consult privately with user C before user C is added to the conference, the application must set the media terminals for the two parties to converse privately.

After this consultation, or if the user does not want to consult, the conference is completed:

pConsultCall->Finish();

The result is illustrated in the following diagram. All three parties in the diagram are connected in a conference.

These pictures are conceptual. From user C's point of view, pConsultCallC is the same as pCallC, and pConsultCallHub is the same as pCallHub. That is, C does not actually receive a new call object and a new CallHub object after A calls Finish. If C has registered the ITCallHubEventNotification interface, C is notified that the number of calls has changed on the CallHub when A calls Finish.

As soon as Finish is called, pConsultCallA transitions to the DISCONNECTED state . The pConsultCallA parameter can no longer be used for any call control, but the application may retain the call object for informational purposes.

Additional parties may be added to the conference by performing Step 2 and Step 3 for each new participant.


Joining a Conference

[This is preliminary documentation and subject to change.]

At times a user may connect to an existing conference. When the application makes a call, it is not aware of other participating calls. The application is only aware of a Call object representing participation in the CallHub and of a CallHub object. This is illustrated in the following drawing.

However, as described in Creating A Conference, the application can use the CallHub object to discover the other calls in the conference:

pCallHub->TotalCalls(&dwCalls);
    // if there are too many calls
    // don't enumerate
    if (dwCalls < MAXCALLS)
    {
        pCallHub->_EnumerateCalls(&pEnumCalls);
    }

The application can then find out about other calls in the conference:


Transferring

[This is preliminary documentation and subject to change.]

The model for transferring is very similar to conferencing. See Creating a Conference for more examples how these methods can be used.

A connection is established to person A. This connection is represented by pCallA. The user decides to transfer B to person C.

First, set up the transfer:

pCallA->SetupTransfer(pCDestAddress,
                         TRUE,
                         &pConsultCallA);

A's call object for the consultation call between A and C is pConsultCallA. C's call object for the consultation call between A and C is pConsultCallC. The CallHub that associates pConsultCallA and pConsultCallC is pConsultCallHub.

At this point, pConsultCallA->CanIConsult may be called. If this returns TRUE, the application can select MediaTerminals and A can converse privately with person C. If this returns FALSE, or the user does not wish to converse privately, the application should move to step 3 by calling:

pConsultCallA->Finish()

After calling Finish, B and C are directly connected, and the local end has been removed from the call. However, pCallA and pConsultCallA are available for informational purposes until the objects are released. As in the conferencing scenario, C has only one call object and one call hub through this whole process, meaning that for C, pConsultCallC = pCallC and pConsultCallHub = pCallHub.


Call and Media Control Code Fragments

[This is preliminary documentation and subject to change.]

The Samples section of the Platform SDK contains complete C++, Java, and Visual Basic® source for several sample applications. These samples are fully compilable.

The following C++ fragments briefly illustrate some basic operations.

  • Selecting an Address
  • Making a Call
  • Receiving a Call
  • Recording a Conversation
  • Accessing the DirectShow Filter Graph


Selecting an Address

[This is preliminary documentation and subject to change.]

The following code fragment demonstrates creating the TAPI object, checking its addresses, and examining an address's media capabilities.

// Create TAPI entry point object
CoCreateInstance(CLSID_TAPI,
                 NULL,
                 CLSCTX_INPROC_SERVER,
                 IID_ITTAPI,
                 (void **) &pTAPI);

// Initialize
pTAPI->Initialize;

// Enumerate addresses
pTAPI->_EnumerateAddresses(&pIEnumAddresses);

// Go through addresses
while ( S_OK == pEnumAddresses->Next(1,
                                     &pAddress,
                                     NULL)))
{
    // determine the media support
    pAddress->QueryInterface(IID_ITMediaSupport
                             &pMediaSupport);
    // in this fragment, the media desired is already known.
    // the application can also use the address object to
    // enumerate the media supported, then choose from there.
    pMediaSupport->QueryMediaType(bstrMediaTypeImInterestedIn,
                                  &bSupport);
    if (bSupport)
    {
        break;
    }
}
// pAddress is now an address I can use.

// determine the terminal support
hr = pAddress->QueryInterface(IID_ITTerminalSupport,
                              &pTerminalSupport);

// just use the default terminal
pTerminalSupport->GetDefaultTerminal(pMediaTypeImInterestedIn,
                                     &pTerminal);

if (!SUCCEEDED(hr))
{
    //failure
}

// now we have a terminal, and we already knew the media, so
// make the call


Making a Call

[This is preliminary documentation and subject to change.]

// user specifies destination address
hr = pAddress->CreateCall(bstrDestAddress,
                          &pCall);

if (hr != S_OK)
{
    // create call failed.
    return;
}

// create a media terminal safearray using media and
// terminals already selected (above), put the safearray
// in a variant, then
// call SelectMediaTerminals
pCall->SelectMediaTerminals(pMediaTerminalSafeArrayvariant);

// the application may also register a callback
// interface at this point

// this will actually make the connection.
// the TRUE parameter in the Connect method
// indicates this connect is synchronous.
pCall->Connect( TRUE );


Receiving a Call

[This is preliminary documentation and subject to change.]

// The app must register the ITAddressCallNotification outgoing
// interface. By registering this interface, the app is telling
// the provider that it wants to wait for calls.

// the app waits for calls
// when one comes in…
// we are given the call info interface on notification.
pCallInfo->QueryInterface(IID_ITBasicCallControl,
                          &pCall);

pCallInfo->EnumerateMediaTerminalsInUse(&pEnumMediaTerminals);

while (S_OK == pEnumMediaTerminals->Next(1,
                                         &pMediaTerminal,
                                         NULL)))
{
    // put media terminal in UI or whatever for
    // user
}

if (bOK)
{
// if user is OK with media terminals, simply call
pCall->Answer();
}
else
{
    pCallInfo->get_Address(&pAddress);
    pAddress->EnumerateStaticTerminals(&pEnumTerminal);
    while (S_OK == pEnumTerminal->Next(1,
                                       &pTerminal
                                       NULL)))
    {
        // put terminal in UI or whatever for user
    }
    // let user select media terminals
    pCall->SelectMediaTerminals(pMediaTerminals);

    // release terminals
    pCall->Answer();
}


Recording a Conversation

[This is preliminary documentation and subject to change.]

pAddress->QueryInterface(IID_ITTerminalSupport,
                         &pTerminalSupport);

pTerminalSupport->EnumerateDynamicTerminalTypes(&pEnumTermTypes);

while (S_OK == pEnumTermTypes->Next(1, &TermType, NULL)))
{
    IID iidTermType;

    // convert bstr to iid
    IIDFromString(TermType,
                  &iidTermType);

    // see if it's the correct type
    if (IIDTermType == CLSID_FileTerminal)
   {
        //create the terminal
        pTerminalSupport->CreateTerminal(TermType,
                                         &pFileTerminal);
    }
}

pEnumTermTypes->Release();

pFileTerminal->SetName(pFileName);

pTAPI->CreateMediaTerminal(bstrMediaType,
                           pFileTerminal
                           &pMediaTerminal);

// put pMediaTerminal into a Variant, then call:
pCall->SelectMediaTerminals(pMediaTerminalVariant);


Accessing the DirectShow Filter Graph

[This is preliminary documentation and subject to change.]

// after a call is connected

pCall->GetDirectShowFilterGraph(&pFilterGraph);

// at this point, the app can manipulate the DirectShow graphs to
// do whatever.


Call and Media Control Reference

[This is preliminary documentation and subject to change.]

The Call and Media Control reference material contains information on interfaces, methods, enumerator interfaces, structures, and types.

You may also wish to search the Platform SDK for information on DirectShow™ and the Component Object Model (COM). TAPI 3.0 uses DirectShow filters and filter managers to control the media stream following connection setup. COM is the basic coding model for TAPI 3.0, and familiarity with it is assumed throughout this document.

Call and Media Control COM Interfaces

Call and Media Control Constants

Call and Media Control Enum Declarations


Call and Media Control COM Interfaces

[This is preliminary documentation and subject to change.]

TAPI version 3.0 has five basic component objects: TAPI, Addresses, Terminals, Calls, and Call Hubs. Each of these objects has at least one interface associated with it. The interfaces have one or more methods. The following table shows the interfaces and methods provided by TAPI 3.0.

Objects | Interfaces
TAPI | ITTAPI ITTAPIEventNotification ITCallHubNotification
Address | ITAddress ITAddressEventNotification
Terminal | ITTerminal IBasicVideo ITBasicAudioTerminal ITFileTerminal ITMediaSupport
Call | ITCallInfo ITBasicCallControl ITCallNotification ITCallTones ITCallTonesNotification ITConsultCall ITParticipantInfo ITChannel ITMultiChannelCall ITMultiChannelNotification
Call Hub | ITCallHub ITCallHubEventNotification
Stand Alone Objects | ITCallStateEvent ITMediaTerminal ITCallMediaEvent ITCollection
COM Standard (Refer to COM section of Platform SDK for details on these interfaces.) | IUnknown IDispatch IEnumXXXX

Outgoing interfaces: ITTAPIEventNotification, ITCallHubNotification, ITAddressEventNotification, ITCallNotification, ITCallTonesNotification, and ITMultiChannelCall


IBasicVideo

[This is preliminary documentation and subject to change.]

The IBasicVideo interface supports the video properties of a generic video window. Generally, this is a video renderer that draws video into a window on the display.

For information on IBasicVideo, refer to the DirectShow™ documentation in the Platform SDKor search on IBasicVideo.


ITAddress

[This is preliminary documentation and subject to change.]

The ITAddress interface is the base interface for the Address object. Applications use this interface to get information about and use the address object.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITAddress Methods | Description
get_State | Returns the current state of the address.
get_AddressName | Retrieves the name of the address.
get_ServiceProviderName | Retrieves the service provider name.
get_TAPIObject | Retrieves pointer to TAPI object.
CreateCall | Creates a new call object that can be used to make an outgoing call.
get_Calls | Collection object for scripting languages.
_EnumerateCalls | Enumerates calls currently on the address.
get_AddressTypes | Collection object for scripting languages.
_EnumerateAddressType | Enumerates address types that this address supports.
RegisterCallTypes | Conveys to TAPI which calls and call events are relevant to an application.


ITAddress::get_State

[This is preliminary documentation and subject to change.]

Returns the current state of the address in pAddressState.

HRESULT get_State(
  ADDRESS_STATE *pAddressState
);

Parameters

pAddressState
[out] Pointer to an ADDRESS_STATE.

Return Values

TBD


ITAddress::get_AddressName

[This is preliminary documentation and subject to change.]

Retrieves displayable name of the address.

HRESULT get_AddressName(
  BSTR *ppName
);

Parameters

ppName
[out] Pointer to BSTR containing the address name.

Return Values

TBD


ITAddress::get_ServiceProviderName

[This is preliminary documentation and subject to change.]

Retrieves the name of the Telephony Service Provider (TSP) which supports this address.

HRESULT get_ServiceProviderName(
  BSTR *ppName
);

Parameters

ppName
[out] Pointer to service provider name.

Return Values

TBD


ITAddress::get_TAPIObject

[This is preliminary documentation and subject to change.]

Retrieves a pointer to the TAPI object which owns this address.

HRESULT get_TAPIObject(
  ITTAPI **ppTapiObject
);

Parameters

ppTapiObject
[out] Pointer to ITTAPI interface.

ReturnValues

TBD


ITAddress::_EnumerateAddressType

[This is preliminary documentation and subject to change.]

Retrieves pointer to address type enumerator. Address types represent the types of destination addresses that the address can use in the Connect method of ITBasicCallControl.

HRESULT _EnumerateAddressType(
  IEnumAddressType **ppEnumAddressType
);

Parameters

ppEnumAddressType
[out] Pointer to IEnumAddressType interface.

ReturnValues

TBD


ITAddress::get_AddressTypes

[This is preliminary documentation and subject to change.]

This method is used by Automation client applications, such as Microsoft® Visual Basic®, to retrieve address types available on the address.

HRESULT get_AddressTypes(
  VARIANT *pVariant
);

Parameters

pVariant
[out] Pointer to a VARIANT that will be filled in with the ITCollection interface of the collection.

Return Values

TBD


ITAddress::CreateCall

[This is preliminary documentation and subject to change.]

Creates a new call object that can be used to make an outgoing call. Upon creation, the call is in the IDLE state and has no media or terminals selected.

HRESULT CreateCall(
  BSTR pDestAddress,
  ITBasicCallControl **ppCall
);

Parameters

pDestAddress
[in] String containing destination address. Format is provider specific.
ppCall
[out] Pointer to ITBasicCallControl interface.

Return Values

TBD


ITAddress::_EnumerateCalls

[This is preliminary documentation and subject to change.]

Enumerates calls currently on the address.

HRESULT _EnumerateCalls(
  IEnumCall **ppCallEnum
);

Parameters

ppCallEnum
[out] Pointer to an IEnumCall interface.

Return Values

TBD


ITAddress::get_Calls

[This is preliminary documentation and subject to change.]

This method is used by Automation client applications, such as Microsoft® Visual Basic®, to retrieve calls currently on the address.

HRESULT get_Calls(
  VARIANT *pVariant
);

Parameters

pVariant
[out] Pointer to a VARIANT that will be filled in with the ITCollection interface of the collection.

Return Values

TBD


ITAddress::RegisterCallTypes

[This is preliminary documentation and subject to change.]

This method is called before an application registers the ITCallNotification outgoing interface. This informs TAPI which calls and call events are relevant to an application. An application can register multiple ITCallNotification interfaces. This method must be called before each registration.

For example, say that an application wants to own one type of call and monitor another type of call, and to register different outgoing interfaces for the calls. It would call RegisterCallTypes(FALSE, TRUE, FALSE, OwnerTypes), then register the Owner interface, then call RegisterCallTypes(FALSE, FALSE, TRUE, MonitorTypes) then register the Monitor interface.

An application can also receive all events on a single interface. For example, by calling RegisterCallTypes(TRUE, TRUE, TRUE, MediaTypes), then registering the interface, the application will receive owner, monitor, and outgoing messages.

The fOutgoing parameter is useful for applications that only make outgoing calls and are not interested in other calls besides their own. By calling RegisterCallTypes(TRUE, FALSE, FALSE, NULL), then registering the interface, the application will only receive event notifications about their own calls.

HRESULT RegisterCallTypes(
  VARIANT_BOOL fOutgoing,
  VARIANT_BOOL fOwner,
  VARIANT_BOOL fMonitor,
  VARIANT MediaTypes
);

Parameters

fOutgoing
[in] Boolean indicating if the application wants events associated with outgoing calls the application has created.
fOwner
[in] Boolean indicating whether the application wants to own incoming calls.
fMonitor
[in] Boolean indicating whether the application wants to monitor calls.
MediaTypes
[in] Array of MediaTypes (in a VARIANT) that indicates types of call the application must monitor.

Return Values

TBD


ITAddressEventNotification

[This is preliminary documentation and subject to change.]

Outgoing interface. An application registers this interface with an Address object to receive asynchronous event notifications concerning the Address.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITAddressEventNotification Methods | Description
AddressEventNotification | This method receives notification of events on an address.


ITAddressEventNotification::AddressEventNotification

[This is preliminary documentation and subject to change.]

This method receives notification of events on an address.

HRESULT AddressEventNotification(
  ITAddress *pAddress,
  ADDRESS_EVENT Event
);

Parameters

pAddress
[in] Pointer to ITAddress interface on which event occurs.
Event
[in] Event that has occurred on the address.

Return Values

TBD


ITBasicAudioTerminal

[This is preliminary documentation and subject to change.]

These methods are taken from the IBasicAudio interface in DirectShow™ .

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITBasicAudioTerminal Methods | Description
put_Volume | Sets volume.
get_Volume | Retrieves volume.
put_Balance | Sets balance.
get_Balance | Retrieves balance.
put_Gain | Sets gain.
get_Gain | Retrieves gain.
QueryFullDuplexSupport | Return indicator of whether audio terminal supports full duplex.


ITBasicAudioTerminal::get_Volume

[This is preliminary documentation and subject to change.]

Retrieves volume.

HRESULT get_Volume(
  long *plVolume
);

Parameters

plVolume
[out] Pointer to volume.

Return Values

TBD


ITBasicAudioTerminal::put_Volume

[This is preliminary documentation and subject to change.]

Sets volume.

HRESULT put_Volume(
  long lVolume
);

Parameters

lVolume
[in] Volume.

Return Values

TBD


ITBasicAudioTerminal::get_Balance

[This is preliminary documentation and subject to change.]

Retrieves balance.

HRESULT get_Balance(
  long *plBalance
);

Parameters

plBalance
[out] Pointer to balance.

Return Values

TBD


ITBasicAudioTerminal::put_Balance

[This is preliminary documentation and subject to change.]

Sets balance.

HRESULT put_Balance(
  long lBalance
);

Parameters

lBalance
[in] Balance.

Return Values

TBD


ITBasicAudioTerminal::get_Gain

[This is preliminary documentation and subject to change.]

Retrieves gain.

HRESULT get_Gain(
  long *plGain
);

Parameters

plGain
[out] Pointer to gain.

Return Values

TBD


ITBasicAudioTerminal::put_Gain

[This is preliminary documentation and subject to change.]

Sets gain.

HRESULT put_Gain(
  long lGain
);

Parameters

lGain
[out] Gain.

Return Values

TBD


ITBasicAudioTerminal::QueryFullDuplexSupport

[This is preliminary documentation and subject to change.]

Returns indicator of whether audio terminal supports full duplex.

HRESULT QueryFullDuplexSupport(
  VARIANT_BOOL *pfSupport
);

Parameters

pfSupport
[out] Boolean variant indicating whether the terminal supports full duplex.

Return Values

TBD


ITBasicCallControl

[This is preliminary documentation and subject to change.]

The ITBasicCallControl interface is used by the application to connect, answer, and perform basic telephony operations on a call object.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITBasicCallControl Methods | Description
SelectMediaTerminals | Select a set of MediaTerminals to use on the call.
UnselectMediaTerminal | Remove the specified ITMediaTerminal from the call.
Connect | Make a connection.
Answer | Accept an incoming call.
Disconnect | Disconnect the call.
Hold | Place or remove the call from the HOLD state.
Handoff | Hand off call to another application.
AddToConference | Start a conference, with the current call included.
SetupTransfer | Transfer the current call to the destination address.
GetDirectShowFilterGraph | Retrieve the DirectShow™ filter graph of the call.


ITBasicCallControl::SelectMediaTerminals

[This is preliminary documentation and subject to change.]

Select a set of ITMediaTerminals to use on the call. To unselect a terminal, use the UnselectMediaTerminal method. Multiple calls to SelectMediaTerminal will continue to select more media terminals — it will not reset the selection.

HRESULT SelectMediaTerminals(
  VARIANT MediaTerminals
);

Parameters

MediaTerminals
[in] Array of MediaTerminals to use on this call.

Return Values

TBD


ITBasicCallControl::UnselectMediaTerminal

[This is preliminary documentation and subject to change.]

Removes the specified MediaTerminal from the call.

HRESULT UnselectMediaTerminal(
  ITMediaTerminal *pMediaTerminal
);

Parameters

pMediaTerminal
[in] Pointer to ITMediaTerminal interface of media terminal to remove from this call.

Return Values

TBD


ITBasicCallControl::Connect

[This is preliminary documentation and subject to change.]

This methods makes a connection. An application can specify if the call is synchronous or asynchronous. If the call is asynchronous, the application will receive information about the call's progress through the ITCallNotification outgoing interface. The application must register the outgoing interface before calling Connect. If it is synchronous, this method will not return until the call is in the connect state or fails, and the application does not have to register the outgoing interface. If asynchronous is specified, Connect may return TRUE, but the actual connection may fail (and the application will be notified through the outgoing interface).

HRESULT Connect(
  VARIANT_BOOL fSync
);

Parameters

fSync
[in] Boolean indicating whether the call is synchronous or asynchronous.

Return Values

TBD


ITBasicCallControl::Answer

[This is preliminary documentation and subject to change.]

This method will answer the call, and thus finish making the connection. This method succeeds only if the call is in the OFFERING state.

HRESULT Answer();

Parameters

None

Return Values

TBD


ITBasicCallControl::Disconnect

[This is preliminary documentation and subject to change.]

Disconnect the call.

HRESULT Disconnect(
  DISCONNECT_CODE code
);

Parameters

code
[in] DISCONNECT_CODE indicating reason for call disconnection.

Return Values

TBD


ITBasicCallControl::Hold

[This is preliminary documentation and subject to change.]

This method will place or remove the call from the HOLD state.

HRESULT Hold(
  VARIANT_BOOL fHold
);

Parameters

fHold
[in] If fHold is TRUE, the call should be put on hold. If fHold FALSE, the call should be removed from hold.

Return Values

TBD


ITBasicCallControl::Handoff

[This is preliminary documentation and subject to change.]

This method hands off the call to another application. This indicates that the application no longer owns the call. There are three ways to hand off a call:

  • Supply the application name to hand off to (called a "directed handoff"). The pMediaType parameter should be NULL in this case. TAPI will check on whether the application is already running, and if so, will try to hand the call to it. If it is not running, TAPI will try to start the application, then hand off to it. If these both fail, TAPI will then try an undirected handoff, using the last known pMediaType.
  • Supply the pMediaType of the call and have TAPI find an appropriate application. The pAppName parameter should be NULL in this case. TAPI will only look at applications that are already running.
  • Supply neither the application name nor the pMediaType. In this case, both pApplicationName and pMediaType are NULL. TAPI will attempt to do an undirected handoff, based on the last known pMediaType.

If TAPI fails to hand off the call, TAPI will call Disconnect on the call.

HRESULT Handoff(
  BSTR pApplicationName,
  BSTR pMediaType
);

Parameters

pApplicationName
[in] Specific application name to handoff call to. Can be full path name or executable name.
pMediaType
[in] MediaType to transfer to.

Return Values

TBD


ITBasicCallControl::AddToConference

[This is preliminary documentation and subject to change.]

The AddToConference method starts a conference with the current call included or adds the call to an existing conference. Adding a call to a conference is a two step process. Use the returned ITConsultCall interface to finish the process. For more information, see Conferencing.

HRESULT AddToConference(
  BSTR pDestAddress,
  VARIANT_BOOL fSync,
  ITConsultCall **ppConsultCall
);

Parameters

pDestAddress
[in] Address to add to the conference.
fSync
[in] Boolean indicator of whether method is called synchronously. See the Connect method of ITBasicCallControl for more information.
ppConsultCall
[out] Will return a pointer to an ITConsultCall interface on success.

Return Values

TBD


ITBasicCallControl::SetupTransfer

[This is preliminary documentation and subject to change.]

Transfer the current call to the destination address. When the transfer is complete, the local address is no longer part of the call, and the remote address is connected to pDestinationAddress. Transfer is a two-step process, similar to Conference. The ppConsultCall parameter represents a direct connection between the local address and the pDestinationAddress. ITConsultCall is used to complete the transfer.

HRESULT SetupTransfer(
  BSTR pDestAddress,
  VARIANT_BOOL fSync,
  ITConsultCall **ppConsultCall
);

Parameters

pDestAddress
[in] Destination address for call transfer.
fSync
[in] Boolean indicator of whether method is called synchronously.
ppConsultCall
[out] Pointer to a consultation call interface that will be filled in with the consult call created for this transfer.

Return Values

TBD


ITBasicCallControl::GetDirectShowFilterGraph

[This is preliminary documentation and subject to change.]

Retrieves the filter graph of the call.

HRESULT GetDirectShowFilterGraph(
  IDispatch **ppDirectShowFilter
);

Parameters

ppDirectShowFilter
[out] Pointer to IDispatch interface of DirectShow™ filter graph.

Return Values

TBD


ITCallHub

Call-center functionality is not implemented for Windows NT® 5 beta 1.

[This is preliminary documentation and subject to change.]

The ITCallHub interface is the main interface for the CallHub object.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITCallHub Methods | Description
_EnumerateCalls | Enumerates calls associated with the call hub.
get_Calls | Collects calls associated with the call hub, for use by scripting languages.
TotalCalls | Get count of total calls associated with the interface.
get_State | Retrieves the current state of the CallHub.


ITCallHub::_EnumerateCalls

Call-center functionality is not implemented for Windows NT® 5 beta 1.

[This is preliminary documentation and subject to change.]

Enumerates calls associated with the CallHub.

HRESULT _EnumerateCalls(
  IEnumCalls **ppEnumCalls
);

Parameters

ppEnumCalls
[out, retval] Pointer to IEnumCalls interface.

Return Values

TBD


ITCallHub::get_Calls

Call-center functionality is not implemented for Windows NT® 5 beta 1.

[This is preliminary documentation and subject to change.]

This method is used by Automation client applications, such as Microsoft® Visual Basic®, to retrieve calls currently on the CallHub.

HRESULT get_Calls(
  VARIANT *pVariant
);

Parameters

pVariant
[out] Pointer to a VARIANT that will be filled in with the ITCollection interface of the collection.

Return Values

TBD


ITCallHub::TotalCalls

Call-center functionality is not implemented for Windows NT® 5 beta 1.

[This is preliminary documentation and subject to change.]

Get number of calls currently associated with the CallHub.

HRESULT TotalCalls(
  PDWORD *pdwTotalCalls
);

Parameters

pdwTotalCalls
[out] Total number of calls that belong to the CallHub.

Return Values

TBD


ITCallHub::get_State

Call-center functionality is not implemented for Windows NT® 5 beta 1.

[This is preliminary documentation and subject to change.]

Retrieves the current state of the CallHub.

HRESULT get_State(
  CALLHUB_STATE *pCallHubState
);

Parameters

pCallHubState
[out] Pointer to CALLHUB_STATE indicator of state.

Return Values

TBD


ITCallHubEventNotification

Call-center functionality is not implemented for Windows NT® 5 beta 1.

[This is preliminary documentation and subject to change.]

Used to acquire information concerning a CallHub object.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITCallHubEventNotification Methods | Description
State | Method to return CALLHUB_STATE on a CallHub object.
CallJoin | Method to return CALLHUB_STATE on a CallHub object.
CallLeave | Method to return ITCallInfo on departed call for CallHub object.


ITCallHubEventNotification::State

Call-center functionality is not implemented for Windows NT® 5 beta 1.

[This is preliminary documentation and subject to change.]

Method to return CALLHUB_STATE on a CallHub object.

HRESULT State(
  CALLHUB_STATE *pNewState
);

Parameters

pNewState
[in] New CallHub state.

Return Values

TBD


ITCallHubEventNotification::CallJoin

Call-center functionality is not implemented for Windows NT® 5 beta 1.

[This is preliminary documentation and subject to change.]

Method to return ITCallInfo on a new call for CallHub object.

HRESULT CallJoin(
  ITCallInfo *pCall
);

Parameters

pCall
[in] Call that joined call hub.

Return Values

TBD


ITCallHubEventNotification::CallLeave

Call-center functionality is not implemented for Windows NT® 5 beta 1.

[This is preliminary documentation and subject to change.]

Method to return ITCallInfo on departed call for CallHub object.

HRESULT CallLeave(
  ITCallInfo *pCall
);

Parameters

pCall
[in] Call that departed call hub.

Return Values

TBD


ITCallHubNotification

Call-center functionality is not implemented for Windows NT® 5 beta 1.

[This is preliminary documentation and subject to change.]

Outgoing interface that can be registered with the TAPI object. Used to receive notifications of new CallHub objects.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITCallHubNotification Methods | Description
GetAddresses | Specify addresses for CallHubs.
NewCallHub | Returns pointer to new CallHub.


ITCallHubNotification::GetAddresses

Call-center functionality is not implemented for Windows NT® 5 beta 1.

[This is preliminary documentation and subject to change.]

This method is called immediately after the interface is registered. The application can specify addresses for which it will receive related CallHubs. The application can return NULL in Addresses, indicating it requires notification of all CallHubs.

HRESULT GetAddresses(
  VARIANT Addresses
);

Parameters

Addresses

[out] Array of ITAddress pointers (in a VARIANT).

Return Values

TBD


ITCallHubNotification::NewCallHub

Call-center functionality is not implemented for Windows NT® 5 beta 1.

[This is preliminary documentation and subject to change.]

New CallHub that appeared in TAPI.

HRESULT NewCallHub(
  ITCallHub *pCallHub
);

Parameters

pCallHub

[in] Pointer to new CallHub object.

Return Values

TBD


ITCallInfo

[This is preliminary documentation and subject to change.]

The ITCallInfo interface is used to provide information about a Call object.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITCallInfo Methods | Description
get_Address | Returns the address object that owns the call.
get_CallState | Returns the current state of the call in pCallState.
get_Privilege | Retrieves the privilege that the application has on the call.
get_MediaTerminalsInUse | Collection of ITMediaTerminal objects in use on the call, for use by scripting languages.
_EnumerateMediaTerminalsInUse | Enumerate the ITMediaTerminal objects in use on the call.
get_ParticipantInfo | Collection of participants for other parties on the conference call, for use by scripting languages.
_EnumerateParticipantInfo | Enumerate participants for other parties on the conference call.
get_ExtendedMediaTypes | Get collection of media types present on call and known to provider but not handled, for use by scripting languages.
_EnumerateExtendedMediaTypes | Enumerates all MediaTypes that are present on the call that the provider knows about, but does not handle.
get_MediaTypesAvailable | Collection of MediaTypes that are available on the call, for use by scripting languages.
_EnumerateMediaTypesAvailable | Enumerates the MediaTypes that are available on the call.


ITCallInfo::get_Address

[This is preliminary documentation and subject to change.]

Returns the address object that owns the call.

HRESULT get_Address(
  ITAddress **ppAddress
);

Parameters

ppAddress
[out] Pointer to address interface.

Return Values

TBD


ITCallInfo::get_CallState

[This is preliminary documentation and subject to change.]

Returns the current state of the call in pCallState.

HRESULT get_CallState(
  CALL_STATE *pCallState
);

Parameters

pCallState
[out] Pointer to variable containing current CALL_STATE type.

Return Values

TBD


ITCallInfo::get_Privilege

[This is preliminary documentation and subject to change.]

Retrieves the privilege that the application has on the call.

HRESULT get_Privilege(
 CALL_PRIVILEGE *pPrivilege
);

Parameters

pPrivilege
[out] Pointer to CALL_PRIVILEGE.

Return Values

TBD


ITCallInfo::_EnumerateMediaTerminalsInUse

[This is preliminary documentation and subject to change.]

Enumerates the ITMediaTerminal objects in use on the call.

HRESULT _EnumerateMediaTerminalsInUse(
  IEnumMediaTerminals **ppEnumMediaTerminals
);

Parameters

ppEnumMediaTerminals
[out] Pointer to ITMediaTerminal enumerator.

Return Values

TBD


ITCallInfo::get_MediaTerminalsInUse

[This is preliminary documentation and subject to change.]

This method is used by Automation client applications, such as Microsoft® Visual Basic®, to retrieve ITMediaTerminal objects in use on the call.

HRESULT get_MediaTerminalsInUse(
  VARIANT *pVariant
);

Parameters

pVariant
[out] Pointer to VARIANT collection object.

Return Values

TBD


ITCallInfo::_EnumerateExtendedMediaTypes

[This is preliminary documentation and subject to change.]

Enumerates all media types that are present on the call that the provider knows about, but does not handle. This usually includes any data streams that are present on the call. The application may use provider-specific interfaces to access these streams.

HRESULT _EnumerateExtendedMediaTypes(
  IEnumExtendedMedia **ppEnumMediaType
);

Parameters

ppEnumMediaType
[out] Pointer to IEnumMediaType.

Return Values

TBD


ITCallInfo::get_ExtendedMediaTypes

[This is preliminary documentation and subject to change.]

This method is used by Automation client applications, such as Microsoft® Visual Basic®, to retrieve media types present on call and known to provider but not handled.

HRESULT get_ExtendedMediaTypes(
  VARIANT *pVariant
);

Parameters

pVariant
[out] Pointer to VARIANT collection object.

Return Values

TBD


ITCallInfo::_EnumerateMediaTypesAvailable

[This is preliminary documentation and subject to change.]

Enumerates the MediaTypesthat are available on the call. This is normally used after a call is connected.

HRESULT _EnumerateMediaTypesAvailable(
  IEnumMediaType **ppEnumMediaType
);

Parameters

ppEnumMediaType
[out] Pointer to IEnumMediaType enumerator interface.

Return Values

TBD


ITCallInfo::get_MediaTypesAvailable

[This is preliminary documentation and subject to change.]

This method is used by Automation client applications, such as Microsoft® Visual Basic®, to retrieve collection of MediaTypes that are available on the call.

HRESULT get_MediaTypesAvailable(
  VARIANT *pVariant
);

Parameters

pVariant
[out] Pointer to VARIANT collection object.

Return Values

TBD


ITCallInfo::_EnumerateParticipantInfo

[This is preliminary documentation and subject to change.]

Enumerate participants for other parties on the conference call.

HRESULT _EnumerateParticipantInfo(
  IEnumParticipantInfo **ppEnumParticipantInfo
);

Parameters

ppEnumParticipantInfo
[out] Pointer to participant enumerator.

Return Values

TBD


ITCallInfo::get_ParticipantInfo

[This is preliminary documentation and subject to change.]

This method is used by Automation client applications, such as Microsoft® Visual Basic®, to retrieve participants for other parties on the conference call.

HRESULT get_ParticipantInfo(
  VARIANT *pVariant
);

Parameters

pVariant
[out] Pointer to VARIANT collection object.

Return Values

TBD


ITCallNotification

[This is preliminary documentation and subject to change.]

Outgoing interface. This interface is registered with an Address object to get all information about calls on that address. An application must have called the RegisterCallTypes method on the Address object before registering this interface. If not, the call to Advise will fail. This interface cannot be unregistered — Unadvise will always fail.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITCallNotification Methods | Description
CallEventNotification | Get information on calls for an address.


ITCallNotification::CallEventNotification

[This is preliminary documentation and subject to change.]

Get information on calls for an address.

HRESULT CallEventNofication(
  ITAddress *pAddress,
  CALL_EVENT_TYPE CallEventType,
  IDispatch *pEvent
);

Parameters

pAddress
[in] Address on which the event occurred.
CallEventType
[in] Type of event in pEvent.
pEvent
[in] Object depends on CallEventType. If CallEventType is CET_CALLOWNER or CET_CALLMONITOR, pEvent is a Call object. If CallEventType is CET_CALLSTATEVENT, pEvent is an ITCallStateEvent object.

Return Values

TBD


ITCallTones

[This is preliminary documentation and subject to change.]

The ITCallTones interface is used to generate tones on a call.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITCallTones Methods | Description
GenerateDTMFs | Generate Dial Tone MultiFrequency (DTMF) tones.


ITCallTones::GenerateDTMFs

[This is preliminary documentation and subject to change.]

Generates the DTMFs in pDTMFs. Synchronous — returns when the DTMFs have been generated.

Valid DTMFs are '0'-'9', 'A','B','C','D','#','*'.

Use the ITCallTonesNotification interface to monitor for incoming tones.

HRESULT GenerateDTMFs(
  BSTR pDTMFs
);

Parameters

pDTMFs
[in] String of DTMFs to generate.

Return Values

TBD


ITCallTonesNotification

[This is preliminary documentation and subject to change.]

This interface is used to notify the application of DTMF tone detection on a call.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

Idispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITCallTonesNotification Methods | Description
DTMF | Called when a Dial Tone MultiFrequency (DTMF) Tone is detected.


ITCallTonesNotification::DTMF

[This is preliminary documentation and subject to change.]

This method is called when a DTMF is detected on the call. A DTMF character is '0'-'9', 'A', 'B', 'C', 'D', '#', and '*'.

HRESULT DTMF(
  ITCallInfo *pCall,
  unsigned char DTMF
);

Parameters

pCall
[in] Call.
DTMF
[in] DTMF character.

Return Values

TBD


ITCallStateEvent

[This is preliminary documentation and subject to change.]

The ITCallStateEvent interface exposes methods that retrieve information on the call event that has occurred.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITCallStateEvent Methods | Description
get_Call | Retrieves pointer to call information interface for the call.
get_Event | Retrieves information on event.
get_Cause | Retrieves cause of event.


ITCallStateEvent::get_Call

[This is preliminary documentation and subject to change.]

Retrieves pointer to call information interface for the call.

HRESULT get_Call(
  ITCallInfo **ppCallInfo
);

Parameters

ppCallInfo
[out] Pointer to ITCallInfo interface.

Return Values

TBD


ITCallStateEvent::get_Event

[This is preliminary documentation and subject to change.]

Retrieves information on event.

HRESULT get_Event(
  CALL_STATE_EVENT *pCallStateEvent
);

Parameters

pCallMediaEvent
[out] Pointer to CALL_STATE_EVENT constant.

Return Values

TBD


ITCallStateEvent::get_Cause

[This is preliminary documentation and subject to change.]

Retrieves the cause associated with this event.

HRESULT get_Cause(
  CALL_STATE_EVENT_CAUSE *pCEC
);

Parameters

pCEC
[out] Pointer to CALL_STATE_EVENT_CAUSE indicator.

Return Values

TBD


ITCallMediaEvent

[This is preliminary documentation and subject to change.]

The ITCallMediaEvent interface exposes methods that retrieve information on the call media event that has occurred.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITCallMediaEvent Methods | Description
get_Call | Retrieves call information interface for call.
get_Event | Retrieves call media event indicator.
get_Cause | Retrieves call media cause indicator.


ITCallMediaEvent::get_Call

[This is preliminary documentation and subject to change.]

Retrieves the call associated with this event.

HRESULT get_Call(
  ITCallInfo **ppCallInfo
);

Parameters

ppCallInfo
[out] Pointer to ITCallInfo interface.

Return Values

TBD


ITCallMediaEvent::get_Event

[This is preliminary documentation and subject to change.]

Retrieves call media event indicator.

HRESULT get_Event(
  CALL_MEDIA_EVENT *pCallMediaEvent
);

Parameters

pCallMediaEvent
[out] Pointer to CALL_MEDIA_EVENT indicator.

Return Values

TBD


ITCallMediaEvent::get_Cause

[This is preliminary documentation and subject to change.]

Retrieves call media cause indicator.

HRESULT get_Cause(
  CALL_MEDIA_CAUSE *pCallMediaCause
);

Parameters

pCallMediaCause
[out] Pointer to CALL_MEDIA_CAUSE indicator.

Return Values

TBD


ITChannel

[This is preliminary documentation and subject to change.]

TBD

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITChannel Methods | Description
SelectTerminals | Selects terminals to use on this channel.
UnselectTerminal | Unselect a terminal from being used on this channel.
SetParticipant | Statically assigns a participant to this channel.
GetParticipant | Gets the participant currently on this channel.


ITChannel::SelectTerminals

[This is preliminary documentation and subject to change.]

Selects terminals to use on this channel. This will override terminal selection made on the call.

TBD: More specific description of use, and code examples.

HRESULT SelectTerminals(
  VARIANT Terminals
);

Parameters

Terminals
[in] Array of terminals to use with this channel, passed to TAPI in a VARIANT.

Return Values

TBD


ITChannel::UnselectTerminal¦

[This is preliminary documentation and subject to change.]

Unselect a terminal being used on this channel.

HRESULT UnselectTerminal(
  ITTerminal *pTerminal
);

Parameters

pTerminal
[in] Terminal to unselect.

Return Values

TBD


ITChannel::SetParticipant

[This is preliminary documentation and subject to change.]

Statically assigns a participant to this channel.

HRESULT SetParticipant(
  ITParticipantInfo *pParticipant
);

Parameters

pParticipant
[in] Participant to statically assign to this channel.

Return Values

TBD


ITChannel::GetParticipant

[This is preliminary documentation and subject to change.]

Gets the participant currently on this channel.

TBD: If participant information is not available, what happens?

HRESULT GetParticipant(
  ITParticipantInfo **ppParticipant
);

Parameters

ppParticipant
[out] Participant currently on this channel.

Return Values

TBD


ITConsultCall

[This is preliminary documentation and subject to change.]

The ITConsultCall interface is used to perform functions specific to consultation calls created from AddToConference and SetupTransfer. An application should use this interface to finish the two-step conference / transfer process.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITConsultCall Methods | Description
CanIConsult | Returns boolean indicator of whether consultation is possible.
Finish | Complete the two-step process involved in conference/transfer.


ITConsultCall::CanIConsult

[This is preliminary documentation and subject to change.]

Returns boolean indicator of whether consultation is possible.

HRESULT CanIConsult(
  VARIANT_BOOL *pfConsult
);

Parameters

pfConsult
[out] On return, this parameter is set to TRUE if a private, direct connection between the local address and destination address can be created.

Return Values

TBD


ITConsultCall::Finish

[This is preliminary documentation and subject to change.]

This method must be called by the application when it wants to complete the two-step process involved in conference/transfer.

HRESULT Finish();

Parameters

None.

Return Values

TBD


ITMediaSupport

[This is preliminary documentation and subject to change.]

The ITMediaSupport interface allows the application to query for media capabilities.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

Idispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITMediaSupport Methods | Description
get_MediaTypes | Get MediaTypesCollection object for scripting.
_EnumerateMediaTypes | Enumerate all the media types the object can handle.
QueryDirectShowSupport | Discover whether a MediaType is supported.
QueryMediaType | Query whether MediaType is supported.


ITMediaSupport::_EnumerateMediaTypes

[This is preliminary documentation and subject to change.]

Returns an IEnumMediaType interface that will enumerate all the media types the object can handle.

HRESULT _EnumerateMediaTypes(
  IEnumMediaType **ppEnumMediaType
);

Parameters

ppEnumMediaType
[out] Pointer to an IEnumMediaType interface.

Return Values

TBD


ITMediaSupport::get_MediaTypes

[This is preliminary documentation and subject to change.]

This method is used by Automation client applications, such as Microsoft® Visual Basic®, to retrieve media types available on the address. Equivalent to _EnumerateMediaTypes.

HRESULT MediaTypes(
  Variant * pVariant
);

Parameters

pVariant
[out] Pointer to list of MediaTypes.

Return Values

TBD


ITMediaSupport::QueryMediaType

[This is preliminary documentation and subject to change.]

This method will return TRUE in pfSupport if the media described by pMediaType is supported.

HRESULT QueryMediaType(
  BSTR pMediaType,
  VARIANT_BOOL *pfSupport
);

Parameters

pMediaType
[in] MediaType BSTR.
pfSupport
[out] Pointer to a BOOL.

Return Values

TBD


ITMediaSupport::QueryDirectShowSupport

[This is preliminary documentation and subject to change.]

Discover whether a media type is supported through DirectShow™.

HRESULT QueryDirectShowSupport(
  BSTR pMediaType,
  VARIANT_BOOL *pfSupport
);

Parameters

pMediaType
[in] Type of media.
pfSupport
[out] Boolean indicating whether the media type is supported.

Return Values

TBD


ITMediaTerminal

[This is preliminary documentation and subject to change.]

The ITMediaTerminal interface is used to describe a media terminal.

Methods in Vtable Order

Iunknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

Idispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITMediaTerminal Methods | Description
get_MediaType | Returns pointer to list of MediaTypes supported by terminal.
get_Terminal | Returns terminal interface pointer.


ITMediaTerminal::get_MediaType

[This is preliminary documentation and subject to change.]

Returns pointer to list of MediaTypes supported by terminal.

HRESULT get_MediaType(
  BSTR *pMediaType
);

Parameters

ppMediaType
Pointer to BSTR containing MediaTypes list.

Return Values

TBD


ITMediaTerminal::get_Terminal

[This is preliminary documentation and subject to change.]

Returns terminal interface pointer.

HRESULT get_Terminal(
  ITTerminal **ppTerminal
);

Parameters

ppTerminal
Pointer to ITTerminal interface.

Return Values

TBD


ITMultiChannelCall

[This is preliminary documentation and subject to change.]

The ITMultiChannelCall interface handles the interface needs of calls that involve multiple media types.

Methods in Vtable Order

Iunknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

Idispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

IMultiChannelCall Methods | Description
get_NumChannels | Get current number of separate channels that the provider is handling.
put_NumChannels | Set the number of channel that the provider should use.
get_Channels | Collection of channels provider is handling, for scripting languages.
_EnumerateChannels | Enumerate channels provider is handling.


ITMultiChannelCall::_EnumerateChannels

[This is preliminary documentation and subject to change.]

Enumerate channels provider is handling.

HRESULT _EnumerateChannels(
  IEnumChannel **ppEnumChannel
);

Parameters

ppEnumChannels
[out] Returns pointer to Channel enumerator.

Return Values

TBD


ITMultiChannelCall::get_NumChannels

[This is preliminary documentation and subject to change.]

Get current number of separate channels that the provider is handling.

HRESULT get_NumChannels(
  ULONG *pulChannels
);

Parameters

pulChannels
[out] Returns number of channels.

Return Values

TBD


ITMultiChannelCall::put_NumChannels

[This is preliminary documentation and subject to change.]

Set the number of channel that the provider should use. This call can fail if the provider cannot handle the number of requested channels.

HRESULT put_NumChannels(
  ULONG ulChannels
);

Parameters

ulChannels
[in] Number of channels to set.

Return Values

TBD


ITMultiChannelCall::get_Channels

[This is preliminary documentation and subject to change.]

This method is used by Automation client applications, such as Microsoft® Visual Basic®, to retrieve channels. Parallel to the _EnumerateChannels.

HRESULT get_Channels(
  VARIANT *pVariant
);

Parameters

pVariant
[out] Pointer to VARIANT collection of ITChannel objects available.

Return Values

TBD


ITMultiChannelNotification

[This is preliminary documentation and subject to change.]

TBD

Methods in Vtable Order

Iunknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

Idispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

IMultiChannelNotification Methods | Description
ChannelChangeEvent | This method is called when the participant on a specific channel changes.


ITMultiChannelNotification::ChannelChangeEvent

[This is preliminary documentation and subject to change.]

This method is called when the participant on a specific channel changes.

HRESULT ChannelChangeEvent(
  ITChannel *pChannel
);

Parameters

pChannel
[in] Channel that changed.

Return Values

TBD


ITParticipantInfo

[This is preliminary documentation and subject to change.]

The ITParticipantInfo interface is used to gather information on conference call participants.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITParticipantInfo Methods | Description
get_Name | Return a string pointer to a participant's name.
get_Address | Return a string pointer to a participant's address name.
get_RelatedCall | Fails if there is no call object associated with the participant or the participant is the local participant.
get_Call | Returns the parent call object (the one that enumerated this participant).


ITParticipantInfo::get_Name

[This is preliminary documentation and subject to change.]

Return a string pointer to a participant's name.

HRESULT get_Name(
  BSTR *ppName
);

Parameters

ppName
[out] Pointer to string containing participant name.

Return Values

TBD


ITParticipantInfo::get_Address

[This is preliminary documentation and subject to change.]

Return a string pointer to a participant's address name.

HRESULT get_Address(
  BSTR *ppAddressName
);

Parameters

ppAddressName
[out] Pointer to string containing participant address.

Return Values

TBD


ITParticipantInfo::get_RelatedCall

[This is preliminary documentation and subject to change.]

Fails if there is no call object associated with the participant or the participant is the local participant.

HRESULT get_RelatedCall(
  ITCallInfo **ppCall
);

Parameters

ppCall
[out] Pointer to call object associated with the participant.

Return Values

TBD


ITParticipantInfo::get_Call

[This is preliminary documentation and subject to change.]

Returns the parent call object (the one that enumerated this participant).

HRESULT get_Call(
  ITCallInfo **ppCall
);

Parameters

ppCall
[out] Pointer to parent call object.

Return Values

TBD


ITTAPI

[This is preliminary documentation and subject to change.]

The ITTAPIinterface is the base interface for the entry point object.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITTAPI Methods | Description
Initialize | Initializes TAPI 3.0.
Shutdown | Shuts down TAPI 3.0.
get_Addresses | Collection of addresses for scripting languages.
_EnumerateAddresses | Enumerates valid addresses.
CreateMediaTerminal | Creates and initializes ITMediaTerminal object.


ITTAPI::Initialize

[This is preliminary documentation and subject to change.]

Initializes TAPI. This method must be called before calling any other TAPI method.

HRESULT Initialize();

Parameters

None.

Return Values

TBD


ITTAPI::Shutdown

[This is preliminary documentation and subject to change.]

Shutdown TAPI.

HRESULT Shutdown();

Parameters

None.

Return Values

TBD


ITTAPI::_EnumerateAddresses

[This is preliminary documentation and subject to change.]

Enumerates valid addresses.

HRESULT _EnumerateAddresses(
  IEnumAddress **ppEnumAddresses
);

Parameters

ppEnumAddresses
[out] Pointer to address enumerator.

Return Values

TBD


ITTAPI::get_Addresses

[This is preliminary documentation and subject to change.]

This method is used by Automation client applications, such as Microsoft® Visual Basic®, to retrieve addresses available to TAPI.

HRESULT get_Addresses(
  Variant *pVariant
);

Parameters

pVariant
[out] Pointer to addresses.

Return Values

TBD


ITTAPI::CreateMediaTerminal

[This is preliminary documentation and subject to change.]

Creates and initializes ITMediaTerminal object.

HRESULT CreateMediaTerminal(
  BSTR pMediaType,
  ITTerminal *pTerminal,
  ITMediaTerminal **ppMediaTerminal
);

Parameters

pMediaType
[in] Pointer to MediaType.
pTerminal
[in] Pointer to ITTerminal.
ppMediaTerminal
[out] Object created.

Return Values

TBD


ITTAPIEventNotification

[This is preliminary documentation and subject to change.]

The ITTAPIEventNotification interface is an outgoing interface for the application to receive asynchronous information about TAPI. An application would register this interface with the TAPI object if it is interested in receiving these notifications.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITTAPIEventNotification Methods | Description
Event | Retrieve information concerning an asynchronous event notification.


ITTAPIEventNotification::Event

[This is preliminary documentation and subject to change.]

Retrieve information concerning an asynchronous event notification.

HRESULT Event(
  TAPI_EVENT Event
);

Parameters

Event
[out] TAPI_EVENT indicator of event.

Return Values

TBD


ITTerminal

[This is preliminary documentation and subject to change.]

The ITTerminal interface is the base interface for a Terminal object.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITTerminal Methods | Description
get_Name | Get a descriptive name of the terminal.
get_State | Retrieves the current state of the terminal.
get_Address | Gets the Address object with which this terminal is associated.
get_TerminalType | Retrieves the TerminalType of the terminal.
get_TerminalClass | Retrieves the TerminalClass of the terminal.
IsStandardTerminal | Determines whether terminal supports Direct Streaming.
CanRender | Determines whether terminal can render the stream.
CanCapture | Determines whether terminal can capture the stream.


ITTerminal::get_Name

[This is preliminary documentation and subject to change.]

Get a descriptive name of the terminal. The name must be usable to the user.

HRESULT get_Name(
  BSTR *ppName
);

Parameters

ppName
[out] Pointer to the name of the terminal.

Return Values

TBD


ITTerminal::get_State

[This is preliminary documentation and subject to change.]

Retrieves the current state of the terminal.

HRESULT get_State(
  TERMINAL_STATE *pTerminalState
);

Parameters

pTerminalState
[out] Pointer to a terminal state enum.

Return Values

TBD


ITTerminal::get_Address

[This is preliminary documentation and subject to change.]

Gets the Address object with which this terminal is associated.

HRESULT get_Address(
  ITAddress **ppAddress
);

Parameters

ppAddress
[out] Pointer to ITAddress interface.

Return Values

TBD


ITTerminal::get_TerminalType

[This is preliminary documentation and subject to change.]

Retrieves the TERMINAL_TYPE of the terminal.

HRESULT get_TerminalType(
  TERMINAL_TYPE *pType
);

Parameters

pType
[out] Pointer to a TERMINAL_TYPE.

Return Values

TBD


ITTerminal::get_TerminalClass

[This is preliminary documentation and subject to change.]

Retrieves the TerminalClass of the terminal.

HRESULT get_TerminalClass(
  BSTR *ppTerminalClass
);

Parameters

pTerminalClass
[out] Terminal Class of the terminal.

Return Values

TBD


ITTerminal::IsStandardTerminal

[This is preliminary documentation and subject to change.]

The pfStandard parameter is set to TRUE if the terminal supports Direct Streaming.

HRESULT IsStandardTerminal(
  VARIANT_BOOL *pfStandard
);

Parameters

pfStandard
[out] Pointer to VARIANT_BOOL.

Return Values

TBD


ITTerminal::CanRender

[This is preliminary documentation and subject to change.]

The pfRender parameter is set to TRUE if the terminal can render the stream.

HRESULT CanRender(
  VARIANT_BOOL *pfRender
);

Parameters

pfRender
[out] Boolean indicating whether terminal can render the media stream.

Return Values

TBD


ITTerminal::CanCapture

[This is preliminary documentation and subject to change.]

The pfCapture parameter is set to TRUE if the terminal can capture the stream.

HRESULT CanCapture(
  VARIANT_BOOL *pfCapture
);

Parameters

pfCapture
[out] Boolean indicating whether terminal can capture the media stream.

Return Values

TBD


ITFileTerminal

[This is preliminary documentation and subject to change.]

TDB

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITFileTerminal Methods | Description
put_FileName | Retrieve name of file to set as a terminal.
get_FileName | Set name of file to set as a terminal.


ITFileTerminal::get_FileName

[This is preliminary documentation and subject to change.]

Retrieve name of file to set as a terminal.

HRESULT get_FileName(
  BSTR pFileName
);

Parameters

pFileName
[out] Pointer to string containing file name.

Return Values

TBD


ITFileTerminal::put_FileName

[This is preliminary documentation and subject to change.]

Set name of file to set as a terminal.

HRESULT put_FileName(
  BSTR *ppszFileName
);

Parameters

ppszFileName
[out] Pointer to file name.

Return Values

TBD


IUnknown

[This is preliminary documentation and subject to change.]

The IUnknown interface lets clients get pointers to other interfaces on a given object through the IUnknown::QueryInterface method, and manage the existence of the object through the IUnknown::AddRef and IUnknown::Release methods. All other Component Object Model (COM) interfaces are inherited, directly or indirectly, from IUnknown. Therefore, the three methods in IUnknown are the first entries in the vtable for every interface.

Note This interface and its methods are fully documented in the COM documentation in the Microsoft® Platform SDK and are only partially documented here for quick reference.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.


IUnknown::AddRef

[This is preliminary documentation and subject to change.]

Increments the reference count for the calling interface on an object. It should be called for every new copy of a pointer to an interface on a given object.

This method is fully documented in the COM documentation in the Microsoft® Platform SDK and is only partially documented here for quick reference.

ULONG AddRef(void);

Parameters

None.

Return Values

Returns an integer from 1 to n, the value of the new reference count. This information is meant to be used for diagnostic/testing purposes only. In certain situations the value might be unstable.


IUnknown::QueryInterface

[This is preliminary documentation and subject to change.]

Returns a pointer to a specified interface on a component to which a client currently holds an interface pointer. This method must call IUnknown::AddRef on the pointer it returns.

This method is fully documented in the COM documentation in the Microsoft® Platform SDK and is only partially documented here for quick reference.

HRESULT QueryInterface(
  REFIID iid,
  void **ppvObject
);

Parameters

iid
[in] Specifies the IID of the interface being requested.
ppvObject
[out] Receives a pointer to an interface pointer to the object on return. If the interface specified in iid is not supported by the object, ppvObject is set to NULL.

Return Values

S_OK
The interface is supported.
S_FALSE
Interface is not supported.


IUnknown::Release

[This is preliminary documentation and subject to change.]

Decrements the reference count for the calling interface on an object. If the reference count on the object falls to zero, the object is freed from memory.

This method is fully documented in the COM documentation in the Microsoft® Platform SDK and is only partially documented here for quick reference.

ULONG Release(void);

Parameters

None

Return Values

Returns the resulting value of the reference count, which is used for diagnostic/testing purposes only. If you need to know that resources have been freed, use an interface with higher level semantics.


IDispatch

[This is preliminary documentation and subject to change.]

The IDispatch interface implements Automation, which makes it easier for interpretive and macro languages to access COM components.

This interface and its methods are fully documented in the COM documentation in the Microsoft® Platform SDK and are only partially documented here for quick reference.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.


IDispatch::GetTypeInfoCount

[This is preliminary documentation and subject to change.]

Retrieves the number of type information interfaces that an object provides (either 0 or 1).

HRESULT GetTypeInfoCount(
  unsigned int FAR *iTInfo
);

Parameters

iTInfo
[out] Returns pointer to count of type information.

Return Values

S_OK
Success
E_NOTIMPL
Failure


IDispatch::GetTypeInfo

[This is preliminary documentation and subject to change.]

Retrieves the type information for an object, which can then be used to get the type information for an interface.

HRESULT GetTypeInfo(
  unsigned int iTInfo,
  LCID lcid,
  ITypeInfo FAR* FAR* ppTInfo
);

Parameters

iTInfo
[in] The type information to return. Pass 0 to retrieve type information for the IDispatch implementation.
lcid
[in] The locale identifier for the type information. An object may be able to return different type information for different languages. This is important for classes that support localized member names. For classes that do not support localized member names, this parameter can be ignored.
ppTInfo
[out] Receives a pointer to the requested type information object.

Return Values

TBD


IDispatch::GetIDsOfNames

[This is preliminary documentation and subject to change.]

Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs, which can be used on subsequent calls to IDispatch::Invoke. The dispatch function DispGetIDsOfNames provides a standard implementation of GetIDsOfNames.

HRESULT GetIDsOfNames(
  REFIID riid,
  OLECHAR FAR* FAR* rgszNames[cNames],
  unsigned int cNames,
  LCID lcid,
  DISPID FAR* rgDispId[cNames]
);

Parameters

riid
[in] Reserved for future use. Must be IID_NULL.
rgszNames
[in] Passed-in array of names to be mapped.
cNames
[in] Count of the names to be mapped.
lcid
[in] The locale context in which to interpret the names.
rgDispId
[out] Caller-allocated array, each element of which contains an identifier (ID) corresponding to one of the names passed in the rgszNames array. The first element represents the member name. The subsequent elements represent each of the member's parameters.

Return Value

S_OK
Success.
E_OUTOFMEMORY
Out of memory.
DISP_E_UNKNOWNNAME
One or more of the names were not known. The returned array of DISPIDs contains DISPID_UNKNOWN for each entry that corresponds to an unknown name.
DISP_E_UNKNOWNLCID
The locale identifier (LCID) was not recognized.


IDispatch::Invoke

[This is preliminary documentation and subject to change.]

Provides access to properties and methods exposed by an object. The dispatch function DispInvoke provides a standard implementation of IDispatch::Invoke.

HRESULT Invoke(
  DISPID dispIdMember,
  REFIID riid,
  LCID lcid,
  WORD wFlags,
  DISPPARAMS FAR* pDispParams,
  VARIANT FAR* pVarResult,
  EXCEPINFO FAR* pExcepInfo,
  unsigned int FAR* puArgErr
);

Parameters

dispIdMember
Identifies the member. Use GetIDsOfNames or the object's documentation to obtain the dispatch identifier.
riid
Reserved for future use. Must be IID_NULL.
lcid
The locale context in which to interpret arguments. The lcid is used by the GetIDsOfNames function, and is also passed to Invoke to allow the object to interpret its arguments specific to a locale.

Applications that do not support multiple national languages can ignore this parameter.

wFlags
Flags describing the context of the Invoke call, include:
DISPATCH_METHOD
The member is invoked as a method. If a property has the same name, both this and the DISPATCH_PROPERTYGET flag may be set.
DISPATCH_PROPERTYGET
The member is retrieved as a property or data member.
DISPATCH_PROPERTYPUT
The member is changed as a property or data member.
DISPATCH_PROPERTYPUTREF
The member is changed by a reference assignment, rather than a value assignment. This flag is valid only when the property accepts a reference to an object.
pDispParams
Pointer to a structure containing an array of arguments, an array of argument DISPIDs for named arguments, and counts for the number of elements in the arrays.
pVarResult
Pointer to the location where the result is to be stored, or Null if the caller expects no result. This argument is ignored if DISPATCH_PROPERTYPUT or DISPATCH_PROPERTYPUTREF is specified.
pExcepInfo
Pointer to a structure that contains exception information. This structure should be filled in if DISP_E_EXCEPTION is returned. Can be Null.
puArgErr
The index within rgvarg of the first argument that has an error. Arguments are stored in pDispParams->rgvarg in reverse order, so the first argument is the one with the highest index in the array. This parameter is returned only when the resulting return value is DISP_E_TYPEMISMATCH or DISP_E_PARAMNOTFOUND.

Return Values

S_OK
Success.
DISP_E_BADPARAMCOUNT
The number of elements provided to DISPPARAMS is different from the number of arguments accepted by the method or property.
DISP_E_BADVARTYPE
One of the arguments in rgvarg is not a valid variant type.
DISP_E_EXCEPTION
The application needs to raise an exception. In this case, the structure passed in pExcepInfo should be filled in.
DISP_E_MEMBERNOTFOUND
The requested member does not exist, or the call to Invoke tried to set the value of a read-only property.
DISP_E_NONAMEDARGS
This implementation of IDispatch does not support named arguments.
DISP_E_OVERFLOW
One of the arguments in rgvarg could not be coerced to the specified type.
DISP_E_PARAMNOTFOUND
One of the parameter DISPIDs does not correspond to a parameter on the method. In this case, puArgErr should be set to the first argument that contains the error.
DISP_E_TYPEMISMATCH
One or more of the arguments could not be coerced. The index within rgvarg of the first parameter with the incorrect type is returned in the puArgErr parameter.
DISP_E_UNKNOWNINTERFACE
The interface identifier passed in riid is not IID_NULL.
DISP_E_UNKNOWNLCID
The member being invoked interprets string arguments according to the LCID, and the LCID is not recognized. If the LCID is not needed to interpret arguments, this error should not be returned.
DISP_E_PARAMNOTOPTIONAL
A required parameter was omitted.


TAPI IEnumXXXX

[This is preliminary documentation and subject to change.]

TBD

IEnumAddress

IEnumAddressType

IEnumChannel

IEnumExtendedMedia

IEnumMediaType

IEnumCall

IEnumTerminal

IEnumTerminalClasses

IEnumMediaTerminals

IEnumParticipantInfo


IEnumAddress

[This is preliminary documentation and subject to change.]

Next, Skip, Reset, Clone

Next returns ITAddress.


IEnumAddressType

[This is preliminary documentation and subject to change.]

Next, Skip, Reset, Clone

Next returns a DWORD.


IEnumMediaType

[This is preliminary documentation and subject to change.]

Next, Skip, Reset, Clone

Next returns a BSTR.


IEnumCall

[This is preliminary documentation and subject to change.]

Next, Skip, Reset, Clone

Next returns ITCallInfo.


IEnumExtendedMedia

[This is preliminary documentation and subject to change.]

Next, Skip, Reset, Clone

Next returns a BSTR representing media.


IEnumChannel

[This is preliminary documentation and subject to change.]

Next, Skip, Reset, Clone

Next returns ITChannel.


IEnumTerminal

[This is preliminary documentation and subject to change.]

Next, Skip, Reset, Clone

Next returns ITTerminal.


IEnumTerminalClasses

[This is preliminary documentation and subject to change.]

Next, Skip, Reset, Clone

Next returns dynamic terminal class (BSTR).


IEnumMediaTerminals

[This is preliminary documentation and subject to change.]

Next, Skip, Reset, Clone

Next returns ITMediaTerminal.


IEnumParticipantInfo

[This is preliminary documentation and subject to change.]

Next, Skip, Reset, Clone

Next returns ITParticipantInfo.


ITCollection

[This is preliminary documentation and subject to change.]

This interface allows Automation clients, such as VB Script, to retrieve collection information. C or C++ programs use enumerator interfaces to retrieve the same information. Collection methods return a VARIANT which contains a pointer to an ITCollection interface.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

ITCollection Methods | Description
get_Count | Returns number of items in collection.
get_Item | Given an index, returns an item in the collection.
get__NewEnum | Returns an enumerator for the collection.


ITCollection::get_Count

[This is preliminary documentation and subject to change.]

Returns number of items in collection.

HRESULT get_Count(
  long *lcount
);

Parameters

lcount
[out] Number of items.

Return Values

TBD


ITCollection::get_Item

[This is preliminary documentation and subject to change.]

Given an index, returns an item in the collection.

HRESULT get_Item(
  long Index,
  VARIANT *pVariant
);

Parameters

Index
[in] Index of item to be retrieved.
pVariant
[out] Pointer to item returned.

Return Values

TBD


ITCollection::get__NewEnum

[This is preliminary documentation and subject to change.]

Returns an enumerator for the collection.

HRESULT get__NewEnum(
  IUnkown **ppNewEnum
);

Parameters

ppNewEnum
[out] Pointer to IUnknown interface of enumerator for this collection.

Return Values

TBD


Call and Media Control Constants

[This is preliminary documentation and subject to change.]

TAPI Version 3.0 call and media control methods use the following constants.

Address Types

Terminal Classes

Media Type


Address Types

[This is preliminary documentation and subject to change.]

T3_ADDRESSTYPE_CONFERENCENAME
T3_ADDRESSTYPE_EMAILNAME
T3_ADDRESSTYPE_DOMAINNAME
T3_ADDRESSTYPE_PHONENUMBER
T3_ADDRESSTYPE_IPADDRESS


Terminal Classes

[This is preliminary documentation and subject to change.]

CLSID_VideoWindowTerm
CLSID_VideoInputTerminal
CLSID_HandsetTerminal
CLSID_HeadsetTerminal
CLSID_SpeakerphoneTerminal
CLSID_MicrophoneTerminal
CLSID_SpeakersTerminal
CLSID_FileTerminal


Media Type

[This is preliminary documentation and subject to change.]

The following MediaTypes are defined:

TAPIMEDIATYPE_AudioIn
An audio media stream that is entering the computer. This media stream would typically be played on speakers, or sent to a handset device.
TAPIMEDIATYPE_AudioOut
An audio media stream that is leaving the computer. This media stream would typically be captured through a microphone or handset device.
TAPIMEDIATYPE_VideoIn
A video media stream that is entering the computer. This media stream would typically be rendered in a video window.
TAPIMEDIATYPE_VideoOut
A video media stream that is leaving the computer. This media stream would typically be captured with a video camera.
TAPIMEDIATYPE_DataModem
A data media stream that is associated with a data modem.
TAPIMEDIATYPE_G3Fax
A data media stream that is associated with G3Fax.


Call and Media Control Enum Declarations

[This is preliminary documentation and subject to change.]

TAPI methods use these enums to set and report on events and states.

ADDRESS_EVENT

ADDRESS_STATE

CALL_EVENT_TYPE

CALL_MEDIA_CAUSE

CALL_MEDIA_EVENT

CALL_PRIVILEGE

CALL_STATE

CALL_STATE_EVENT_CAUSE

DIRECTION

DISCONNECT_CODE

TAPI_EVENT

TERMINAL_STATE

TERMINAL_TYPE


ADDRESS EVENT

[This is preliminary documentation and subject to change.]

Used to check on address availability by the AddressEventNotification method of the ITAddressEventNotification interface.

typedef enum
{
    AE_INSERVICE,
    AE_OUTOFSERVICE,
    AE_CLOSED
} ADDRESS_EVENT;

Members

AE_INSERVICE
Normal state – meaning the address can be used.
AE_OUTOFSERVICE
The address is temporarily out of service, but may go back into service at some time.
AE_CLOSED
The address has been permanently removed or close, and will not return.


ADDRESS STATE

[This is preliminary documentation and subject to change.]

This enum is used by the get_State method of the ITAddress interface.

typedef enum
{
    AS_INSERVICE,
    AS_OUTOFSERVICE
} ADDRESS_STATE;

Members

AS_INSERVICE
Normal state – meaning the address can be used.
AS_OUTOFSERVICE
The address is temporarily out of service, but may go back into service at some time.


CALL EVENT TYPE

[This is preliminary documentation and subject to change.]

Used by ITCallEventNotification method of the ITCallNotification interface to indicate type of call event which has occurred.

typedef enum
{
    CET_CALLOWNER,
    CET_CALLMONITOR,
    CET_CALLSTATEVENT,
    CET_CALLMEDIAEVENT
} CALL_EVENT_TYPE;

Members

CET_CALLOWNER
Call owner changed.
CET_CALLMONITOR
Call monitor changed.
CET_CALLSTATEVENT
The state of the call has changed.
CET_CALLMEDIAEVENT
The media of a call has changed.


CALL MEDIA CAUSE

[This is preliminary documentation and subject to change.]

typedef enum
{
    CMC_NOTDEFINED

} CALL_MEDIA_CAUSE;

Members

CMC_NOTDEFINED
Call media has not been defined.


CALL MEDIA EVENT

[This is preliminary documentation and subject to change.]

typedef enum
{
    CME_NOTDEFINED

} CALL_MEDIA_EVENT;

Members

CME_NOTDEFINED
Call media has not been defined.


CALL PRIVILEGE

[This is preliminary documentation and subject to change.]

These indicate the privilege that the application has on the call.

typedef enum
{
    CP_OWNER,
    CP_MONITOR

} CALL_PRIVILEGE;

Members

CP_OWNER
The application is the owner of the call.
CP_Monitor
The application is a monitor of the call.


CALL STATE EVENT CAUSE

[This is preliminary documentation and subject to change.]

TBD: Interfaces and methods which use these.

typedef enum
{
    CEC_NONE,
    CEC_DISCONNECT_NORMAL,
    CEC_DISCONNECT_BUSY,
    CEC_DISCONNECT_BADADDRESS,
    CEC_DISCONNECT_NOANSWER,
    CEC_DISCONNECT_CANCELLED,
    CEC_DISCONNECT_REJECTED,
    CEC_DISCONNECT_FAILED
} CALL_STATE_EVENT_CAUSE

Members

CEC_DISCONNECT_NORMAL
This cause indicates that the call was disconnected as part of the normal life cycle of the call (that is, the call was over, so it was disconnected).
CEC_DISCONNECT_BUSY
An outgoing call failed to connect because the remote end was busy.
CEC_DISCONNECT_BADADDRESS
An outgoing call failed because the destination address was bad.
CEC_DISCONNECT_NOANSWER
An outgoing call failed because the remote end was not answered.
CEC_DISCONNECT_CANCELLED
An outgoing call failed because the caller disconnected.
CEC_DISCONNECT_REJECT
The outgoing called was rejected by the remote end.
CEC_DISCONNECT_FAILED
The call failed to connect for some other reason.


CALL STATE

[This is preliminary documentation and subject to change.]

Used by get_CallState, get_Event, and get_Cause.

typedef enum
{
    CS_IDLE,
    CS_INPROGRESS,
    CS_CONNECTED,
    CS_DISCONNECTED,
    CS_OFFERING,
    CS_HOLD,
    CS_QUEUED
} CALL_STATE

Members

CS_IDLE
The call has been created, but Connect has not been called yet. A call can never transition into the IDLE state.
CS_INPROGRESS
Connect has been called, and the service provider is working on making a connection. This state is only valid on outgoing calls. This message is optional, as a service provider may have a call transition directly to the CONNECTED state.
CS_CONNECTED
Call has been connected to the remote end, and communication can take place.
CS_DISCONNECTED
Call has been disconnected. There are several causes for disconnection. See details below.
CS_OFFERING
A new call has appeared, and is being offered to an application. An application can either call Connect or Disconnect while the call is in the offering state.
CS_HOLD
The call is in the hold state.
CS_QUEUED
The call is queued.

Following is a table of all valid call state transitions.

CS_IDLE | INPROGRESS
CS_INPROGRESS | CONNECTED
 | FAILED
CS_CONNECTED | HOLD
 | DISCONNECTED
CS_DISCONNECTED | nothing – call should be freed
CS_OFFERING | CONNECTED
 | DISCONNECTED
CS_HOLD | CONNECTED
 | DISCONNECTED
CS_QUEUED | CONNECTED
 | DISCONNECTED


DIRECTION

[This is preliminary documentation and subject to change.]

Used to describe the direction of the media stream, with respect to the local machine.

typedef enum
{
    D_CAPTURE,
    D_RENDER
} DIRECTION;

Members

D_CAPTURE
The stream is captured on the local machine, and the data is sent out to the remote end of the connection.
D_RENDER
The stream is arriving from the remote end of the connection, and can be rendered to a terminal device for the user to see/hear.


DISCONNECT CODE

[This is preliminary documentation and subject to change.]

These codes are used in the Disconnect method in the ITBasicCallControl interface.

typedef enum
{
    DC_NORMAL,
    DC_NOANSWER,
    DC_REJECTED
} DISCONNECT_CODE

Members

DC_NORMAL
The call is being disconnected as part of the normal cycle of the call.
DC_NOANSWER
The call is being disconnected because it has not been answered (For example, an application may set a certain amount of time for the user to answer the call. If the user does not answer, the application can call Disconnect with the NOANSWER code.)
DC_REJECTED
The user rejected the offered call.


TAPI EVENT

[This is preliminary documentation and subject to change.]

Used to notify an application that a change has occurred in the TAPI object. Returned by the Event method of the ITTAPIEventNotification interface.

typedef enum
{
    TE_REINITIALIZE,
    TE_NEWADDRESS
}TAPI_EVENT;

Members

TE_REINITIALIZE
The TAPI object has been reinitialized.
TE_NEWADDRESS
A new address has appeared (usually, through Plug and Play). The application should re-enumerate the addresses to get access to the new address.


TERMINAL STATE

[This is preliminary documentation and subject to change.]

These codes describe the current state of a terminal device.

typedef enum
{
    TS_INUSE,
    TS_NOTINUSE
} TERMINAL_STATE;

Members

TS_INUSE
The terminal is currently in use.
TS_NOTINUSE
The terminal is not currently in use.


TERMINAL TYPE

[This is preliminary documentation and subject to change.]

These codes describe the type of the terminal.

typedef enum
{
    TT_STATIC,
    TT_DYNAMIC
} TERMINAL_TYPE;

Members

TT_STATIC
A static terminal is a terminal that cannot be created — usually refers to hardware device. TAPI enumerates these terminals.
TT_DYNAMIC
A terminal type that can be created. The application must call CreateTerminal to use this type of terminal.


About Rendezvous

[This is preliminary documentation and subject to change.]

Rendezvous controls provide a mechanism to advertise and discover multiparty conferences. The following describes a set of COM components and interfaces to send and receive announcements of multiparty, multimedia conferences.

Rendezvous is part of the IP Multicast Conferencing Platform designed for Windows® operating systems.

Features

  • Provides the abstraction of a conference directory for manipulating announcements of multimedia conferences.
  • Provides security through authentication, encryption, and per-announcement access control. (Not implemented for Windows NT® 5 beta 1.)
  • Provides a common schema for a conference announcement, enabling searches by attribute values. Allows extensions through a provider-maintained attribute (conference blob) in the schema. Provides a framework for synchronization of attributes shared between the common schema and the contents of the provider-interpreted attribute.

Architecture

The following descriptions and diagram illustrate key aspects of the system architecture.

  • The client may manipulate conferences stored on an ILS dynamic directory server with Rendezvous controls. The Lightweight Directory Access Protocol (LDAP) is used to communicate with the server.
  • The Rendezvous controls provide dual COM interfaces for scripting and programming.
  • A Session Announcement Protocol (SAP) server with direct access to the internet listens to conference announcements on the Internet and populates ILS dynamic server with the conference information. Similarly, it also announces the locally created conferences whose scope includes the Internet. (The SAP server is not planned for Windows NT 5.)


Rendezvous Code Fragments

[This is preliminary documentation and subject to change.]

The code fragments in this section demonstrate how the described component interfaces may be used.

Conference Directory Enumeration

Create conference announcement (with default attributes)

Modify a known conference


Rendezvous Reference

[This is preliminary documentation and subject to change.]

The following table lists components and interfaces provided by Rendezvous to advertise and discover multiparty conferences.

Components | Interfaces | Description
Conference Directory | ITConferenceDirectory | Main interface used to add, delete, and find conferences on an ILS or NTDS server.
Conference Announcement | ITConference | Allows an application to get and set generic information specific to the conference, such as conference name and start time.
 | ITNotification | Notifies application of changes in conference characteristics.
Conference Blob <Provider> | ITConferenceBlob | Provides access to specific conference information.
 | ITNotification | Notifies application of changes in conference characteristics.
Conference Blob <SDP> | ITConferenceBlob | Provides access to specific conference information.
 | ITSdp | Session Description Protocol blob.
 | ITAttributeList | Allows getting and setting of uninterpreted attributes.
 | ITConnection | Provides methods to manipulate connection factors such as conference address, scope, bandwidth, etc.
 | ITNotification | Notifies application of changes in conference characteristics.
Media | ITMedia | Allows getting and setting of basic media properties such as the media name and transport protocol.
 | ITAttributeList | Allows getting and setting of uninterpreted attributes.Allows access to and setting of attributes (strings).
 | ITConnection | Provides methods to manipulate connection factors such as conference address, scope, bandwidth, etc. Provides methods to manipulate connection factors such as network type.
Media Collection | ITMediaCollection | Allows media access by index. Enables creation and deletion of media.
Time | ITTime | Provides access to a set of activation times for the session.
Time Collection | ITTimeCollection | Allows time-component access by index. Enables creation and deletion of time components.
Conference Announcement Enumerator | IEnumVARIANT | Allows enumeration of any filtered subset of conference announcements in the conference directory.

Rendezvous Enum Declarations

Notification Identifier

Advertising Scope


Conference Directory

[This is preliminary documentation and subject to change.]

The conference directory contains a set of conference announcements that were created in the local area network via LDAP.

Conference Directory Interfaces | Description
ITConferenceDirectory | Creates, retrieves, and deletes conference announcements.


ITConferenceDirectory

[This is preliminary documentation and subject to change.]

This is a COM interface for the conference directory component. It provides the following functionality:

  • Creates enumerators to enumerate filtered subsets of conference announcements in the conference directory.
  • Creates a conference announcement.
  • Retrieves a conference by name.
  • Deletes a conference announcement by name.
IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITConferenceDirectory Methods | Description
get_DirectoryPath | Returns the absolute path to the directory (BSTR).
get_ServerName | Returns server name (BSTR).
Init | Binds the conference directory component to the specified absolute directory path name (BSTR, BSTR).
CreateConference | Returns a conference announcement that (including the constituent conference blob) is created with default property values.
DeleteConference | Deletes the conference announcement possessing the supplied (relative) name (BSTR).
GetConference | Returns a conference announcement with the specified name (BSTR).
get_Filter | Gets the filter (VARIANT).
put_Filter | Sets the filter (VARIANT).
get__NewEnum | Returns a conference enumerator object that implements IEnumVARIANT.


ITConferenceDirectory::get_DirectoryPath

[This is preliminary documentation and subject to change.]

This method returns a pointer to the absolute path name for the conference directory.

HRESULT get_DirectoryPath(
  BSTR *ppDirectoryPath
);

Parameters

ppDirectoryPath
[out] Pointer to string containing the path of the conference directory.

Return Values

TBD


ITConferenceDirectory::get_ServerName

[This is preliminary documentation and subject to change.]

The get_ServerName method returns a pointer to the server name.

HRESULT get_ServerName(
  BSTR *ppServerName
);

Parameters

ppServerName
[out] Pointer to string containing the name of the server.

Return Values

TBD


ITConferenceDirectory::get_Filter

[This is preliminary documentation and subject to change.]

Retrieves a property filter.

HRESULT get_Filter(
  BSTR  *ppFilter
);

Parameters

ppFilter
[out] Pointer to property filter.

Return Values

TBD


ITConferenceDirectory::put_Filter

[This is preliminary documentation and subject to change.]

Sets a property filter.

HRESULT put_Filter(
  BSTR  pFilter
);

Parameters

pFilter
[in] Filter to be entered.

Return Values

TBD


ITConferenceDirectory::get__NewEnum

[This is preliminary documentation and subject to change.]

Returns an enumerator for the collection.

HRESULT get__NewEnum(
  IUnknown **pVal
);

Parameters

pVal
[out] Pointer to IUnknown of IEnumVARIANT enumerator interface.

Return Values

TBD


ITConferenceDirectory::Init

[This is preliminary documentation and subject to change.]

Binds the conference directory component to the specified server name and absolute directory path.

HRESULT Init(
  BSTR *pServerName,
  BSTR *pDirectoryName
);

Parameters

pServerName
[in] Pointer to name of server.
pDirectoryName
[in] Pointer to absolute path for directory.

Return Values

TBD


ITConferenceDirectory::GetConference

[This is preliminary documentation and subject to change.]

Returns a conference announcement with the specified name.

HRESULT GetConference(
  BSTR pConferenceName,
  ITConference **ppConference
);

Parameters

pConferenceName
[in] Name of conference.
ppConference
[out] Pointer to ITConference interface.

Return Values

TBD


ITConferenceDirectory::CreateConference

[This is preliminary documentation and subject to change.]

Returns a conference announcement that (including the constituent conference blob) is created with default values.

HRESULT CreateConference(
  BSTR pConferenceName,
  ITConference **ppConference
);

Parameters

pConferenceName
[in] Name of conference.
ppConference
[out] Pointer to ITConference interface of new conference.

Return Values

TBD

Remarks

After the conference is created by this method, its conference blob will not be written to ILS server until 1) ITConferenceBlob::CommitBlob is explicitly called, or 2) ITConference::Release is called. Without a conference blob, some operations, such as ITConferenceDirectory::GetConference will fail with error "The parameter is incorrect".

The following code fragments demonstrate the usage:

pITConfDir->CreateConference(bszConfName, &pITConf);
pITConf->Release();   // This will decrement the reference count to 0
                      // and the conference blob will be written to server.

or:

pITConfDir->CreateConference(bszConfName, &pITConf);
pITConf->QueryInterface(IID_ITConferenceBlob, &pITConfBlob);
pITConfBlob->CommitBlob();  // Conference blob will be written to server.


ITConferenceDirectory::DeleteConference

[This is preliminary documentation and subject to change.]

Deletes the conference announcement possessing the supplied (relative) name.

HRESULT DeleteConference(
  BSTR pConferenceName
);

Parameters

pConferenceName
[in] Pointer to name of conference.

Return Values

TBD


Conference Announcement

[This is preliminary documentation and subject to change.]

A conference announcement may be created by a user in the local network, or it may be added to the conference directory by an external SAP gateway for the WAN. (The SAP gateway is not planned for NT 5.0). The conference blob attribute allows for provider-specific extensions, as the provider is free to store its attributes in this uninterpreted attribute. An attribute in the conference announcement schema identifies the provider. The section on conference blob describes a mechanism for synchronizing any conference announcement attributes that are duplicated in the schema.

The conference blob interfaces are aggregated by this component.

Conference Announcement Interface | Description
ITConference | Retrieves and sets conference announcement data attributes.
ITNotification | Notifies application of changes in conference characteristics.


ITConference

[This is preliminary documentation and subject to change.]

This interface provides methods that allow an application to set and get conference details. Conference attributes that are mirrored in the conference blob are synchronized using the ITNotification interface.

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITConference Methods | Description
get_Name | Get conference name.
put_Name | Sets conference name.
get_ProtocolId | Get protocol identification.
put_ProtocolId | Sets protocol identification.
get_SubType | Get sub type.
put_SubType | Sets sub type.
get_Originator | Get originator.
put_Originator | Sets originator.
get_AnnouncementScope | Get announcement scope.
put_AnnouncementScope | Sets announcement scope.
get_AdvertisingScope | Get advertising scope.
put_AdvertisingScope | Sets advertising scope.
get_Url | Get URL.
put_Url | Sets URL.
get_Description | Get description of conference.
put_Description | Sets description of conference.
get_IsEncrypted | Get whether conference is encrypted. (Not implemented for Windows NT® 5 beta 1.)
put_IsEncrypted | Sets whether conference is encrypted. (Not implemented for Windows NT 5 beta 1.)
get_ConferenceBlob | Get pointer to conference blob.
put_ConferenceBlob | Sets pointer to conference blob.
GetStartTime | Get start time of conference.
SetStartTime | Sets start time of conference.
GetStopTime | Get stop time of conference.
SetStopTime | Sets stop time of conference.


ITConference::get_Name

[This is preliminary documentation and subject to change.]

Get conference name.

HRESULT get_Name(
  BSTR *ppName
);

Parameters

ppName
[out] Pointer to conference name.

Return Values

TBD


ITConference::put_Name

[This is preliminary documentation and subject to change.]

Sets conference name.

HRESULT put_Name(
  BSTR pName
);

Parameters

pName
[in] Pointer to conference name.

Return Values

TBD


ITConference::get_ProtocolId

[This is preliminary documentation and subject to change.]

Get protocol identification.

HRESULT get_ProtocolId(
  BSTR *ppProtocolID
);

Parameters

ppProtocolID
[out] Pointer to protocol identifier.

Return Values

TBD


ITConference::put_ProtocolId

[This is preliminary documentation and subject to change.]

Sets protocol identification.

HRESULT put_ProtocolId(
  BSTR pProtocolID
);

Parameters

pProtocolID
[in] Pointer to protocol identifier.

Return Values

TBD


ITConference::get_SubType

[This is preliminary documentation and subject to change.]

Get sub type.

HRESULT get_SubType(
  BSTR *ppSubType
);

Parameters

ppSubType
[out] Pointer to sub type.

Return Values

TBD


ITConference::put_SubType

[This is preliminary documentation and subject to change.]

Sets sub type.

HRESULT put_SubType(
  BSTR pSubType
);

Parameters

pSubType
[in] Pointer to sub type.

Return Values

TBD


ITConference::get_Originator

[This is preliminary documentation and subject to change.]

Get originator.

HRESULT get_Originator(
  BSTR *ppOriginator
);

Parameters

*ppOriginator
[out] Pointer to originator.

Return Values

TBD


ITConference::put_Originator

[This is preliminary documentation and subject to change.]

Sets originator.

HRESULT put_Originator(
  BSTR pOriginator
);

Parameters

pOriginator
[in] Pointer to originator.

Return Values

TBD


ITConference::get_AnnouncementScope

[This is preliminary documentation and subject to change.]

Get announcement scope.

HRESULT get_AnnouncementScope(
  BSTR *ppAnnouncementScope
);

Parameters

ppAnnouncementScope
[out] Pointer to announcement scope.

Return Values

TBD


ITConference::put_AnnouncementScope

[This is preliminary documentation and subject to change.]

Sets announcement scope.

HRESULT put_AnnouncementScope(
  BSTR pAnnouncementScope
);

Parameters

pAnnouncementScope
[in] Pointer to announcement scope.

Return Values

TBD


ITConference::get_AdvertisingScope

[This is preliminary documentation and subject to change.]

Get advertising scope.

HRESULT get_AdvertisingScope(
  RND_ADVERTISING_SCOPE *ppAdvertisingScope
);

Parameters

ppAdvertisingScope
[out] Pointer to advertising scope.

Return Values

TBD


ITConference::put_AdvertisingScope

[This is preliminary documentation and subject to change.]

Sets advertising scope.

HRESULT put_AdvertisingScope(
  RND_ADVERTISING_SCOPE pAdvertisingScope
);

Parameters

pAdvertisingScope
[in] Pointer to advertising scope.

Return Values

TBD


ITConference::get_Url

[This is preliminary documentation and subject to change.]

Get URL.

HRESULT get_Url(
  BSTR *ppUrl
);

Parameters

ppUrl
[out] Pointer to URL.

Return Values

TBD


ITConference::put_Url

[This is preliminary documentation and subject to change.]

Sets URL.

HRESULT put_Url(
  BSTR pUrl
);

Parameters

pUrl
[in] Pointer to URL.

Return Values

TBD


ITConference::get_Description

[This is preliminary documentation and subject to change.]

Get description of conference.

HRESULT get_Description(
  BSTR *ppDescription
);

Parameters

ppDescription
[out] Pointer to description of conference.

Return Values

TBD


ITConference::put_Description

[This is preliminary documentation and subject to change.]

Sets description of conference.

HRESULT put_Description(
  BSTR pDescription
);

Parameters

pDescription
[in] Pointer to description of conference.

Return Values

TBD


ITConference::get_IsEncrypted

[This is preliminary documentation and subject to change.]

Get whether conference is encrypted. (Not implemented for Windows NT 5 beta 1.)

HRESULT get_IsEncrypted(
  BSTR *ppIsEncrypted
);

Parameters

ppIsEncrypted
[out] Pointer to whether conference is encrypted.

Return Values

TBD


ITConference::put_IsEncrypted

[This is preliminary documentation and subject to change.]

Sets whether conference is encrypted. (Not implemented for Windows NT 5 beta 1.)

HRESULT put_IsEncrypted(
  BSTR pIsEncrypted
);

Parameters

pIsEncrypted
[in] Pointer to whether conference is encrypted.

Return Values

TBD


ITConference::get_ConferenceBlob

[This is preliminary documentation and subject to change.]

Get pointer to conference blob.

HRESULT get_ConferenceBlob(
  BSTR *ppConferenceBlob
);

Parameters

ppConferenceBlob
[out] Pointer to conference blob.

Return Values

TBD


ITConference::put_ConferenceBlob

[This is preliminary documentation and subject to change.]

Sets pointer to conference blob.

HRESULT put_ConferenceBlob(
  BSTR pConferenceBlob
);

Parameters

pConferenceBlob
[out] Pointer to conference blob.

Return Values

TBD


ITConference::GetStartTime

[This is preliminary documentation and subject to change.]

Get user start time of conference.

HRESULT GetStartTime(
  USHORT *pYear,
  BYTE *pMonth,
  BYTE *pDay,
  BYTE *pHour,
  BYTE *pMinute
);

Parameters

pYear
[out] Year of conference start time.
pMonth
[out] Month of conference start time.
pDay
[out] Day of conference start time.
pHour
[out] Hour of conference start time.
pMinute
[out] Minute of conference start time.

Return Values

TBD


ITConference::SetStartTime

[This is preliminary documentation and subject to change.]

Sets user start time of conference.

HRESULT SetStartTime(
  USHORT Year,
  BYTE Month,
  BYTE Day,
  BYTE Hour,
  BYTE Minute
);

Parameters

Year
[in] Year of conference start time.
Month
[in] Month of conference start time.
Day
[in] Day of conference start time.
Hour
[in] Hour of conference start time.
Minute
[in] Minute of conference start time.

Return Values

TBD


ITConference::GetStopTime

[This is preliminary documentation and subject to change.]

Get user stop time of conference.

HRESULT GetStopTime(
  USHORT *pYear,
  BYTE *pMonth,
  BYTE *pDay,
  BYTE *pHour,
  BYTE *pMinute
);

Parameters

pYear
[out] Year of conference stop time.
pMonth
[out] Month of conference stop time.
pDay
[out] Day of conference stop time.
pHour
[out] Hour of conference stop time.
pMinute
[out] Minute of conference stop time.

Return Values

TBD


ITConference::SetStopTime

[This is preliminary documentation and subject to change.]

Sets user stop time of conference.

HRESULT SetStopTime(
  USHORT Year,
  BYTE Month,
  BYTE Day,
  BYTE Hour,
  BYTE Minute
);

Parameters

Year
[in] Year of conference stop time.
Month
[in] Month of conference stop time.
Day
[in] Day of conference stop time.
Hour
[in] Hour of conference stop time.
Minute
[in] Minute of conference stop time.

Return Values

TBD


Conference Blob <Provider>

[This is preliminary documentation and subject to change.]

This is a generic name and refers to any component that hides the details of the conference blob attribute in a conference announcement. An attribute in the conference announcement schema (ProtocolId) identifies the conference blob provider component that interprets and maintains the conference blob.

The parameters needed for creating the conference blob may be specified through a provider-specific interface. Some of these parameters duplicate attributes of the conference announcement and, a mechanism to keep them synchronized is provided. The provider-specific details of the conference blob are transparent to the conference announcement. Only the conference blob implementation is aware of exactly which parameters are shared with the conference announcement.

A conference announcement aggregates this component and uses it to obtain the value of the conference blob attribute. These two components communicate using the ITNotification interface to keep shared attributes in sync. In other words, when an attribute from an available list of attributes is modified in either of them, the other component is notified via a notification that identifies the changed attribute and its new value.

A Session Description Protocol (SDP) conference blob component is provided.

Conference Blob Interfaces | Description
ITConferenceBlob | Manipulates the conference blob in its textual form.
ITNotification | Maintains synchronization with the aggregating conference announcement component. May also support provider-specific interfaces to manipulate the properties.


ITConferenceBlob

[This is preliminary documentation and subject to change.]

This is a mandatory COM interface for the conference blob component. It enables a user of the component to remain independent of the provider-specific extensions while being able to manipulate the conference blob in its textual form. A method is also provided to create a default conference blob with a given name.

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITConferenceBlob Methods | Description
Init | Initialize conference blob.
CreateDefault | Create a default conference blob.
CommitBlob | Commit changes to conference blob.
get_IsModified | Indicates whether blob has been modified.
get_ConferenceBlob | Get pointer to conference blob.
put_ConferenceBlob | Set conference blob.
get_NotificationOwner | Get pointer to ITNotification interface for conference.
put_NotificationOwner | Set pointer to ITNotification interface for conference.


ITConferenceBlob::Init

[This is preliminary documentation and subject to change.]

Initialize conference blob.

HRESULT Init();

Parameters

None

Return Values

TBD


ITConferenceBlob::CommitBlob

[This is preliminary documentation and subject to change.]

Commit changes to conference blob.

HRESULT CommitBlob();

Parameters

None

Return Values

TBD


ITConferenceBlob::get_IsModified

[This is preliminary documentation and subject to change.]

Indicates whether blob has been modified.

HRESULT get_IsModified(
    VARIANT_BOOL *pfIsModified
);

Parameters

pfIsModified
[out] Pointer to boolean variant, TRUE if blob has been modified and FALSE if it has not been modified.

Return Values

TBD


ITConferenceBlob::get_ConferenceBlob

[This is preliminary documentation and subject to change.]

Get pointer to conference blob.

HRESULT get_ConferenceBlob(
   BSTR *ppBlob
);

Parameters

ppBlob
[out] Pointer to conference blob.

Return Values

TBD


ITConferenceBlob::put_ConferenceBlob

[This is preliminary documentation and subject to change.]

Set conference blob.

HRESULT put_ConferenceBlob(
   BSTR pBlob
);

Parameters

pBlob
[in] Pointer to BSTR containing conference blob.

Return Values

TBD


ITConferenceBlob::CreateDefault

[This is preliminary documentation and subject to change.]

Create a default conference blob.

HRESULT CreateDefault(
  BSTR pName
);

Parameters

pName
[in] Pointer to name of conference.

Return Values

TBD


ITConferenceBlob::get_NotificationOwner

[This is preliminary documentation and subject to change.]

Get pointer to ITNotification interface for conference.

HRESULT get_NotificationOwner(
  ITNotification **ppOwner
);

Parameters

ppOwner
[out] Pointer to ITNotification interface pointer for conference.

Return Values

TBD


ITConferenceBlob::put_NotificationOwner

[This is preliminary documentation and subject to change.]

Get pointer to ITNotification interface for conference.

HRESULT put_NotificationOwner(
  ITNotification *pOwner
);

Parameters

pOwner
[in] Pointer to ITNotification interface for conference.

Return Values

TBD


Conference Blob <SDP>

[This is preliminary documentation and subject to change.]

This component is an implementation of the SDP (Session Description Protocol) conference blob.

This component exports two mandatory interfaces -- ITConferenceBlob to obtain the conference blob in its textual form and ITNotification to maintain synchronization with the aggregating component. It may also support provider-specific interfaces to manipulate the properties programmatically. The SDP has certain global attributes (including user's personal information), connection (bandwidth, address and encryption information) attributes, timing information, generic uninterpreted attributes and one or more media. Each of these attribute sets is exposed by a separate interface, one of which is also exposed by the media component.

Conference Blob <SDP> Interfaces | Description
ITConferenceBlob | Provides access to specific conference information.
ITSdp | Session Description Protocol blob.
ITAttributeList | Allows getting and setting of uninterpreted attributes.Allows for access to and setting of attributes (strings).
ITConnection | Provides methods to manipulate connection factors such as conference address, scope, bandwidth, etc.
ITNotification | Notifies application of changes in conference characteristics.


ITSdp

[This is preliminary documentation and subject to change.]

This is a provider-specific COM interface for the conference blob component. It provides the following functionality:

  • Provides access to some of the properties that are common to all the media. These include attributes pertaining to creator's personal information, session description, and address type information.
  • Provides the starting point for accessing the time and media collections through properties.
IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITSdp Methods | Description
get_IsValid | Validates the SDP blob for structure and field values.
get_ProtocolVersion | Gets the SDP protocol version.
get_SessionId | Gets the 32bit NTP value that serves as the session id (ULONG). This is generated automatically when the session is created.
get_SessionVersion | Gets the 32bit (ideally NTP) value that serves as the session version (ULONG). Although this is generated automatically when the session is created, the user is responsible for changing this when the SDP is modified.
put_SessionVersion | Sets session version.
get_MachineAddress | Gets the machine address of the originating host (BSTR).
put_MachineAddress | Sets the machine address of the originating host (BSTR).
get_SessionName | Gets the session name (BSTR). This has to be an ASCII convertible string if the character set is ASCII. (It can be any BSTR string otherwise.)
put_SessionName | Sets the session name.
get_SessionInfo | Gets the session information (BSTR). This has to be an ASCII convertible string if the character set is ASCII. (It can be any BSTR string otherwise.)
put_SessionInfo | Sets the session information.
get_Uri | Gets the URI (BSTR). A URI is a Universal Resource Identifier as used by WWW clients. This URI should be a pointer to additional information about the session.
put_Uri | Sets the URI.
GetEmailNames | Gets array of email names and addresses associated with conference blob. These are passed as a VARIANT.
SetEmailNames | Sets array of email names and addresses associated with conference blob. These are passed as a VARIANT.
GetPhoneNumbers | Gets the phone numbers. These are passed as a VARIANT.
SetPhoneNumbers | Sets the phone numbers. These are passed as a VARIANT.
get_CharacterSet | Gets the character set used for the SessionName and SessionInfo properties.
put_CharacterSet | Sets the character set used for the SessionName and SessionInfo properties.
get_UserName | Get user name.
put_UserName | Set user name.
get_MediaCollection | Get pointer to ITMediaCollection interface for conference.
get_TimeCollection | Get pointer to ITTimeCollection interface for conference.


ITSdp::get_IsValid

[This is preliminary documentation and subject to change.]

Validates the SDP blob for structure and field values.

HRESULT get_IsValid(
  VARIANT_BOOL *pfIsValid
);

Parameters

pfIsValid
[out] Indicates whether blob structure is valid.

Return Values

TBD


ITSdp::get_ProtocolVersion

[This is preliminary documentation and subject to change.]

Gets the SDP protocol version.

HRESULT get_ProtocolVersion(
  USHORT *pProtocolVersion
);

Parameters

pProtocolVersion
[out] Pointer to protocol version.

Return Values

TBD


ITSdp::get_SessionId

[This is preliminary documentation and subject to change.]

Gets the 32-bit NTP value that serves as the session id (ULONG). This is generated automatically when the session is created.

HRESULT get_SessionId(
  ULONG *pSessionId
);

Parameters

pSessionId
[out] Pointer to session id.

Return Values

TBD


ITSdp::get_SessionVersion

[This is preliminary documentation and subject to change.]

Gets the 32-bit (ideally NTP) value that serves as the session version (ULONG). While this is generated automatically when the session is created, the user is responsible for changing this when the SDP is modified.

HRESULT get_SessionVersion(
  ULONG *pSessionVersion
);

Parameters

pSessionVersion
[out] Pointer to session version identifier.

Return Values

TBD


ITSdp::get_CharacterSet

[This is preliminary documentation and subject to change.]

Gets the character set used for the SessionName and SessionInfo properties. This corresponds to a "a=charset:<character set>" line in the SDP and, therefore, should not be manipulated through the generic attribute list interface. The default value is ASCII and the line is not present in such a case.

HRESULT get_CharacterSet(
  BSTR *ppCharacterSet
);

Parameters

ppCharacterSet
[out] Pointer to BSTR of character set.

Return Values

TBD


ITSdp::get_UserName

[This is preliminary documentation and subject to change.]

Get user name.

HRESULT get_UserName(
  BSTR *ppUserName
);

Parameters

ppUserName
[out] Pointer to BSTR containing user name.

Return Values

TBD


ITSdp::get_MachineAddress

[This is preliminary documentation and subject to change.]

Gets the machine address of the originating host (BSTR).

HRESULT get_MachineAddress(
  BSTR *ppMachineAddress
);

Parameters

ppMachineAddress
[out] Pointer to BSTR containing machine address of conference host.

Return Values

TBD


ITSdp::GetPhoneNumbers

[This is preliminary documentation and subject to change.]

Gets the phone numbers. These are passed as VARIANTs.

HRESULT GetPhoneNumbers(
  VARIANT *pNumbers,
  VARIANT *pNames
);

Parameters

pNumbers
[out] VARIANT list of phone numbers.
pNames
[out] VARIANT list of names.

Return Values

TBD


ITSdp::SetPhoneNumbers

[This is preliminary documentation and subject to change.]

Sets the phone numbers. These are passed as VARIANTs.

HRESULT SetPhoneNumbers(
  VARIANT Numbers,
  VARIANT Names
);

Parameters

Numbers
[in] VARIANT containing phone numbers.
Names
[in] VARIANT containing names.

Return Values

TBD


ITSdp::get_SessionName

[This is preliminary documentation and subject to change.]

Gets the session name (BSTR). This has to be an ASCII convertible string if the character set is ASCII. (It can be any BSTR string otherwise.)

HRESULT get_SessionName(
  BSTR *ppSessionName
);

Parameters

ppSessionName
[out] Session name.

Return Values

TBD


ITSdp::get_SessionInfo

[This is preliminary documentation and subject to change.]

Gets the session information (BSTR). This has to be an ASCII convertible string if the character set is ASCII. (It can be any BSTR string otherwise.)

HRESULT get_SessionInfo(
  BSTR *ppSessionInfo
);

Parameters

ppSessionInfo
[out] Session information.

Return Values

TBD


ITSdp::get_Uri

[This is preliminary documentation and subject to change.]

Gets the URI (BSTR). A URI is a Universal Resource Identifier as used by WWW clients. This URI should be a pointer to additional information about the session.

HRESULT get_Uri(
  BSTR *ppUri
);

Parameters

ppUri
[out] Universal Resource Identifier.

Return Values

TBD


ITSdp::put_SessionVersion

[This is preliminary documentation and subject to change.]

Sets session version.

HRESULT put_SessionVersion(
  ULONG SessionVersion
);

Parameters

SessionVersion
[in] Session version value.

Return Values

TBD


ITSdp::put_CharacterSet

[This is preliminary documentation and subject to change.]

Sets the character set used for the SessionName and SessionInfo properties. This corresponds to a "a=charset:<character set>" line in the SDP and, therefore, should not be manipulated through the generic attribute list interface. The default value is ASCII and the line is not present in such a case.

HRESULT put_CharacterSet(
  BSTR pCharacterSet
);

Parameters

pCharacterSet
[in] Pointer to BSTR of character set.

Return Values

TBD


ITSdp::put_UserName

[This is preliminary documentation and subject to change.]

Set user name.

HRESULT put_UserName(
  BSTR pUserName
);

Parameters

pUserName
[in] User name.

Return Values

TBD


ITSdp::get_MediaCollection

[This is preliminary documentation and subject to change.]

Get pointer to ITMediaCollection interface for conference.

HRESULT get_MediaCollection(
  ITMediaCollection **ppMediaCollection
);

Parameters

ppMediaCollection
[out] Pointer to ITMediaCollection.

Return Values

TBD


ITSdp::get_TimeCollection

[This is preliminary documentation and subject to change.]

Get pointer to ITTimeCollection interface for conference.

HRESULT get_TimeCollection(
  ITTimeCollection **ppTimeCollection
);

Parameters

ppTimeCollection
[out] Pointer to ITTimeCollection.

Return Values

TBD


ITSdp::put_MachineAddress

[This is preliminary documentation and subject to change.]

Sets the machine address of the originating host (BSTR).

HRESULT put_MachineAddress(
  BSTR pMachineAddress
);

Parameters

pMachineAddress
[in] Address of host machine.

Return Values

TBD


ITSdp::put_SessionName

[This is preliminary documentation and subject to change.]

Sets the session name.

HRESULT put_SessionName(
  BSTR pSessionName
);

Parameters

pSessionName
[in] Session Name.

Return Values

TBD


ITSdp::put_SessionInfo

[This is preliminary documentation and subject to change.]

Sets the session information.

HRESULT put_SessionInfo(
  BSTR pSessionInfo
);

Parameters

pSessionInfo
[in] Session information.

Return Values

TBD


ITSdp::put_Uri

[This is preliminary documentation and subject to change.]

Sets the URI.

HRESULT put_Uri(
  BSTR pUri
);

Parameters

pUri
[in] Universal Resource Identifier.

Return Values

TBD


ITSdp::GetEmailNames

[This is preliminary documentation and subject to change.]

Gets array of email names associated with conference blob.

HRESULT GetEmailNames(
  VARIANT *pAddresses,
  VARIANT *pNames
);

Parameters

pAddresses
[out] VARIANT of email addresses.
pNames
[out] VARIANT of names.

Return Values

TBD


ITSdp::SetEmailNames

[This is preliminary documentation and subject to change.]

Sets array of email names and addresses associated with conference blob.

HRESULT SetEmailNames(
  VARIANT Addresses,
  VARIANT Names
);

Parameters

Addresses
[in] VARIANT of email addresses.
Names
[in] VARIANT of names.

Return Values

TBD


Media Collection

[This is preliminary documentation and subject to change.]

This component enables enumeration, creation, and deletion of media in an SDP component.

Media Manipulator Interfaces | Description
ITMediaCollection | Represents media.


ITMediaCollection

[This is preliminary documentation and subject to change.]

This is a provider-specific COM interface for the Conference Blob <SDP> component. It provides the following functionality:

  • Allows media access by index.
  • Enables creation and deletion of media.
IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITMediaCollection Methods | Description
get_Count | Gets the number of media in the session.
get_Item | Returns the media corresponding to the specified index.
get__NewEnum | Returns an enumerator for the collection.
Create | Creates a new media with default properties and returns it.
Delete | Deletes the media corresponding to the specified index.


ITMediaCollection::get_Count

[This is preliminary documentation and subject to change.]

Gets the number of media in the session.

HRESULT get_Count(
  ULONG *pVal
);

Parameters

pVal
[out] Count of media in the session.

Return Values

TBD


ITMediaCollection::get_Item

[This is preliminary documentation and subject to change.]

Returns the media corresponding to the specified index.

HRESULT get_Item(
  ULONG Index,
  ITMedia **pVal
);

Parameters

Index
[in] Index of item to get.
pVal
[out] Pointer to ITMedia interface for desired item.

Return Values

TBD


ITMediaCollection::get__NewEnum

[This is preliminary documentation and subject to change.]

Returns an enumerator for the collection.

HRESULT get__NewEnum(
  IUnknown **pVal,
);

Parameters

pVal
[out] Pointer to IUnknown interface of collection.

Return Values

TBD


ITMediaCollection::Create

[This is preliminary documentation and subject to change.]

Creates a new media with default properties and returns it.

HRESULT Create(
  ULONG Index,
  ITMedia **ppMedia
);

Parameters

Index
[in] Index for new item.
ppMedia
[out] Pointer to ITMedia interface created.

Return Values

TBD


ITMediaCollection::Delete

[This is preliminary documentation and subject to change.]

Deletes the media corresponding to the specified index.

HRESULT DeleteMedia(
  ULONG Index
);

Parameters

Index
[in] Index of media to be deleted.

Return Values

TBD


Media

[This is preliminary documentation and subject to change.]

This component is a representation of a media in an SDP component. It exports interfaces to get and set the basic media properties. It provides interfaces to manipulate the connection attributes and any generic attributes for the media.

Media Manipulator Interfaces | Description
ITMedia | Allows getting and setting of basic media properties such as the media name and transport protocol.
ITAttributeList | Allows getting and setting of uninterpreted attributes.Allows access to and setting of attributes (strings).
ITConnection | Provides methods to manipulate connection factors such as conference address, scope, bandwidth, etc.


ITMedia

[This is preliminary documentation and subject to change.]

This component is a representation of a media in an SDP component. It exports methods to get and set media properties

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITMedia Methods | Descriptions
get_MediaName | Gets the media name (BSTR). Defined media are audio, video, whiteboard, text and data.
put_MediaName | Sets the media name (BSTR). Defined media are audio, video, whiteboard, text and data.
get_StartPort | Gets the 16-bit port value (USHORT) for the first port.
get_NumPorts | Gets the number of ports (USHORT) needed for the session.
get_TransportProtocol | Gets the transport protocol (BSTR). This is specified in addition to the media format so that the same standard media format may be carried over different transport protocols even when the network protocol is the same.
put_TransportProtocol | Sets the transport protocol (BSTR). This is specified in addition to the media format so that the same standard media format may be carried over different transport protocols even when the network protocol is the same.
get_FormatCodeList | Gets the list of media payload format codes.
put_FormatCodeList | Sets the list of media payload format codes.
get_MediaTitle | Gets the media title (BSTR). This is mainly for user information or display purposes. This has to be an ASCII convertible string if the character set is ASCII. (It can be any BSTR string otherwise.)
put_MediaTitle | Sets the media title (BSTR). This is mainly for user information or display purposes. This has to be an ASCII convertible string if the character set is ASCII. (It can be any BSTR string otherwise.)
SetPortInfo | Sets the 16-bit port value (USHORT) for the first port and number of ports needed for session.


ITMedia::get_MediaName

[This is preliminary documentation and subject to change.]

Gets the media name (BSTR). Defined media are audio, video, whiteboard, text and data.

HRESULT get_MediaName(
  BSTR *ppMediaName
);

Parameters

ppMediaName
[out] Name of media, such as audio.

Return Values

TBD


ITMedia::get_TransportProtocol

[This is preliminary documentation and subject to change.]

Gets the transport protocol (BSTR). This is specified in addition to the media format so that the same standard media format may be carried over different transport protocols even when the network protocol is the same, such as with. Vat PCM audio and RTP PCM audio.

HRESULT get_TransportProtocol(
  BSTR *ppProtocol
);

Parameters

ppProtocol
[out] Pointer to BSTR representation of transport protocol.

Return Values

TBD


ITMedia::get_FormatCodeList

[This is preliminary documentation and subject to change.]

Gets the list of media payload format codes. The list is returned as a VARIANT. When a list of payload formats is given, this implies that all of these formats may be used in the session, but the first of these formats is the default format for the session.

HRESULT get_FormatCodeList(
  VARIANT *pList
);

Parameters

pList
[out] Array of media payload format codes.

Return Values

TBD


ITMedia::get_MediaTitle

[This is preliminary documentation and subject to change.]

Gets the media title (BSTR). This is mainly for user information or display purposes. This has to be an ASCII convertible string if the character set is ASCII. (It can be any BSTR string otherwise.)

HRESULT get_MediaTitle(
  BSTR *ppMediaTitle
);

Parameters

ppMediaTitle
[out] Pointer to string containing title of the media.

Return Values

TBD


ITMedia::put_MediaName

[This is preliminary documentation and subject to change.]

Sets the media name (BSTR). Defined media are audio, video, whiteboard, text and data.

HRESULT put_MediaName(
  BSTR pMediaName
);

Parameters

pMediaName
[in] Media name to set.

Return Values

TBD


ITMedia::get_StartPort

[This is preliminary documentation and subject to change.]

Gets the 16-bit port value (USHORT) for the first port.

HRESULT get_StartPort(
  USHORT *pStartPort
);

Parameters

pStartPort
[out] Value of first port.

Return Values

TBD


IMedia::put_NumPorts

ITMedia::get_NumPorts

[This is preliminary documentation and subject to change.]

Gets the number of ports (USHORT) needed for the session.

HRESULT get_NumPorts(
  USHORT *pNumPorts
);

Parameters

pNumPorts
[out] Number of ports needed.

Return Values

TBD


ITMedia::put_TransportProtocol

[This is preliminary documentation and subject to change.]

Sets the transport protocol (BSTR). This is specified in addition to the media format so that the same standard media format may be carried over different transport protocols even when the network protocol is the same, such as with Vat PCM audio and RTP PCM audio.

HRESULT put_TransportProtocol(
  BSTR pProtocol
);

Parameters

pProtocol
[in] Transport protocol.

Return Values

TBD


ITMedia::put_FormatCodeList

[This is preliminary documentation and subject to change.]

Sets the list of media payload format codes. The list is returned as a VARIANT. When a list of payload formats is given, this implies that all of these formats may be used in the session, but the first of these formats is the default format for the session.

HRESULT put_FormatCodeList(
  VARIANT List
);

Parameters

List
[in] List of media payload format codes.

Return Values

TBD


ITMedia::put_MediaTitle

[This is preliminary documentation and subject to change.]

Sets the media title (BSTR). This is mainly for user information or display purposes. This has to be an ASCII convertible string if the character set is ASCII. (It can be any BSTR string otherwise.)

HRESULT put_MediaTitle(
  BSTR pMediaTitle
);

Parameters

pMediaTitle
[in] String containing title of the media.

Return Values

TBD


ITMedia::SetPortInfo

[This is preliminary documentation and subject to change.]

Sets the 16-bit port value (USHORT) for the first port and number of ports needed for session.

HRESULT SetPortInfo(
  USHORT StartPort,
  USHORT NumPorts
);

Parameters

StartPort
[in] Starting port.
NumPorts
[in] Number of ports.

Return Values

TBD


ITMedia::get_NumPorts

[This is preliminary documentation and subject to change.]

Gets the number of ports (USHORT) needed for the session.

HRESULT get_NumPorts(
  USHORT *pNumPorts
);

Parameters

pNumPorts
[out] Number of ports.

Return Values

TBD


Time Collection

[This is preliminary documentation and subject to change.]

This component enables enumeration, creation and deletion of time-related attributes in an SDP component.

Time Collection InterFaces | Description
ITTimeCollection | Allows time component access by index. Enables creation and deletion of time components.


ITTimeCollection

[This is preliminary documentation and subject to change.]

This is a provider-specific COM interface for the Conference Blob <SDP> component. It provides the following functionality:

  • Allows time component access by index.
  • Enables creation and deletion of time components.
IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITTimeCollection Methods | Description
get_Count | Get number of items in collection.
get_Item | Given an index, returns an item in the collection.
get__NewEnum | Returns an enumerator for the collection.
Create | Create an ITTime component.
Delete | Delete an ITTime component.


ITTimeCollection::get_Count

[This is preliminary documentation and subject to change.]

Get number of items in collection.

HRESULT get_Count(
  ULONG*pVal
);

Parameters

pVal
[out] Number of items in collection.

Return Values

TBD


ITTimeCollection::get_Item

[This is preliminary documentation and subject to change.]

Get an item from the collection using an index.

HRESULT get_Item(
  ULONG Index,
  ITTime **pVal
);

Parameters

Index
[in] Index of item to get.
pVal
[out] Pointer to ITTime desired interface.

Return Values

TBD


ITTimeCollection::get__NewEnum

[This is preliminary documentation and subject to change.]

Returns an enumerator for the collection.

HRESULT get__NewEnum(
  IUnknown **pVal
);

Parameters

pVal
[out] Pointer to IUnknown pointer of enurmerator interface.

Return Values

TBD


ITTimeCollection::Create

[This is preliminary documentation and subject to change.]

Create new ITTime component.

HRESULT Create(
  ULONG Index,
  ITTime **ppTime
);

Parameters

Index
[in] Index of item to create.
ppTime
[out] Point to ITTime component created.

Return Values

TBD


ITTimeCollection::Delete

[This is preliminary documentation and subject to change.]

Delete an ITTime component.

HRESULT Delete(
  ULONG Index
);

Parameters

Index
[in] Index of ITTime component to be deleted.

Return Values

TBD


Time

[This is preliminary documentation and subject to change.]

This component is a representation of the time attributes in an SDP component. There may be several lines with the "t" type. This component does not expose the corresponding "r" and "z" types.

It exports interfaces to get and set the time properties. It also provides interfaces to any generic attributes for the media.

Time Interfaces | Description
ITTime | Provides access to a set of activation times for the session.


ITTime

[This is preliminary documentation and subject to change.]

This is a provider-specific COM interface for the time component. It provides the following functionality:

  • Provides access to a set of activation times for the session.
IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITTime Methods | Remark
get_StartTime | Gets the 32-bit NTP starting time value (ULONG). The session is considered active from this time.
put_StartTime | Sets the 32-bit NTP starting time value (ULONG). The session is considered active from this time.
get_StopTime | Gets the NTP ending time value (ULONG). If the end time is 0, then the session is not bounded.
put_StopTime | Sets the NTP ending time value (ULONG). If the end time is 0, then the session is not bounded.


ITTime::get_StartTime

[This is preliminary documentation and subject to change.]

Gets the 32-bit NTP starting time value (ULONG). The session is considered active from this time.

HRESULT get_StartTime(
  ULONG *pTime
);

Parameters

pTime
[out]

Return Values

TBD


ITTime::get_StopTime

[This is preliminary documentation and subject to change.]

Gets the NTP ending time value (ULONG). If the end time is 0, the session is not bounded.

HRESULT get_StopTime(
  ULONG *pTime
);

Parameters

pTime
[out]

Return Values

TBD


ITTime::put_StartTime

[This is preliminary documentation and subject to change.]

Sets the 32-bit NTP starting time value (ULONG). The session is considered active from this time.

HRESULT put_StartTime(
  ULONG Time
);

Parameters

Time
[in]

Return Values

TBD


ITTime::put_StopTime

[This is preliminary documentation and subject to change.]

Sets the NTP ending time value (ULONG). If the end time is 0, the session is not bounded.

HRESULT put_StopTime(
  ULONG Time
);

Parameters

Time
[in]

Return Values

TBD


Conference Announcement Enumerator

[This is preliminary documentation and subject to change.]

A conference directory allows enumeration of any subset of its conference announcements through a conference directory enumerator. While an enumerator instance is dependent upon a conference directory, it is a separate component.

Conference Announcement Enumerator | Description
IEnumVARIANT | Enables enumeration of a filtered subset of conference announcements in the conference directory with Next, Skip, Reset and Clone methods.


IEnumVARIANT

[This is preliminary documentation and subject to change.]

Enumerator interfaces are a standard part of COM. They provide a means of moving within list of similar objects.

Enumerator Interfaces | Description
Next | Return pointer to next item in list.
Skip | Skip next item.
Reset | Return to start of list.
Clone | Copy list.


Notification Identifier

[This is preliminary documentation and subject to change.]

Dispatch id indicating which aggregating component property has changed. Returned by the ITNotification::ChangeNotification method.

typedef enum
{
    NI_SUB_TYPE = 1,
    NI_ORIGINATOR = 2,
    NI_ANNOUNCEMENT_SCOPE = 3,
    NI_ADVERTISING_SCOPE= 4,
    NI_URL = 5,
    NI_DESCRIPTION = 6,
    NI_START_TIME = 7,
    NI_STOP_TIME = 8,
    NI_CONFERENCE_BLOB = 9
} RND_NOTIFICATION_ID;

List of items synchronized between the conference and SDP conference blob.

Conference | SDP Blob and dependent Time and Media instances
SubType | None
Originator | UserName
AnnouncementScope | None
AdvertisingScope | Max ttl among all c fields
Url | Url
Description | SessionInfo
StartTime | Minimum start time among all the t fields
StopTime | Maximum stop time among all the t fields
ConferenceBlob | ConferenceBlob


Advertising Scope

[This is preliminary documentation and subject to change.]

Specifies how widely a conference announcement is distributed. Values correspond to the advertising scope property on the ITConference interface. The advertising scope property is kept in sync with the max ttl value for the SDP blob. RND_ADVERTISING_SCOPE values are used to signal change notifications between the conference and the SDP blob components.

typedef enum RND_ADVERTISING_SCOPE
{
    AS_LOCAL = 1,
    AS_SITE = 2,
    AS_REGION = 3,
    AS_WORLD = 4
} RND_ADVERTISING_SCOPE;

Mapping between scope string value, enum value, and ttl based on SDP Internet draft.

Scope String Value | RND_ADVERTISING_SCOPE | ttl
Local | AS_LOCAL | 1
Site | AS_SITE | 15
Region | AS_REGION | 63
World | AS_WORLD | 127


Shared Interfaces

[This is preliminary documentation and subject to change.]

The following interfaces are used by more than one components.

Interfaces: | Shared By Components:
ITAttributeList | Conference Blob <SDP> Media
ITConnection | Conference Blob <SDP> Media
ITNotification | Conference Announcement Conference Blob <Provider>


ITAttributeList

[This is preliminary documentation and subject to change.]

This COM interface allows for getting and setting of uninterpreted attributes. A substring "a=" is prepended to these attributes before adding them to the SDP blob. Similarly, when an attribute string is passed to the user, the substring is removed. Regarding the position of the attribute strings in the SDP packet, it makes the assumption that all attribute strings exist just before the media attributes are specified (after all the common attributes).

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITAttributeList Methods | Description
get_Count | Gets the number of attributes.
get_Item | Returns the attribute (BSTR) specified by the index (USHORT).
Add | Adds the attribute (BSTR) at the specified index (USHORT).
Delete | Deletes the attribute at the specified index (USHORT).
get_AttributeList | Gets the list of attributes (VARIANT).
put_AttributeList | Sets the list of attributes (VARIANT).


ITAttributeList::get_Count

[This is preliminary documentation and subject to change.]

Gets the number of attributes.

HRESULT get_Count(
  USHORT *pVal
);

Parameters

pVal
[out] Count of attributes in list.

Return Values

TBD


ITAttributeList::get_AttributeList

[This is preliminary documentation and subject to change.]

Gets the list of attributes (VARIANT).

HRESULT get_AttributeList(
  VARIANT *pVal
);

Parameters

pVal
[out] Array of attributes.

Return Values

TBD


ITAttributeList::put_AttributeList

[This is preliminary documentation and subject to change.]

Sets the list of attributes (VARIANT).

HRESULT put_AttributeList(
  VARIANT *newVal
);

Parameters

newVal
[in] Array of attributes to set.

Return Values

TBD


ITAttributeList::get_Item

[This is preliminary documentation and subject to change.]

Returns the attribute (BSTR) specified by the index (USHORT).

HRESULT get_Item(
  USHORT Index,
  BSTR *pVal
);

Parameters

Index
[in] Index of item to get.
pVal
[out] Values of item.

Return Values

TBD


ITAttributeList::Add

[This is preliminary documentation and subject to change.]

Adds the attribute (BSTR) at the specified index (USHORT).

HRESULT Add(
  USHORT Index,
  BSTR pAttribute
);

Parameters

Index
[in] Index of attribute to added.
pAttribute
[in] Value of attribute to added.

Return Values

TBD


ITAttributeList::Delete

[This is preliminary documentation and subject to change.]

Deletes the attribute at the specified index (USHORT).

HRESULT Delete(
  USHORT Index
);

Parameters

Index
[in] Index of attribute to delete.

Return Values

TBD


ITConnection

[This is preliminary documentation and subject to change.]

This COM interface provides the following functionality:

  • Provides access to the address and ttl information for the session.
  • Provides access to the bandwidth information.
  • Enables manipulation of the encryption key. (Not implemented for Windows NT 5 beta 1.)
IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

ITConnection Methods | Description
get_NetworkType | Get the network type.
put_NetworkType | Set the network type.
get_AddressType | Get the Address type.
put_AddressType | Set the Address type.
get_StartAddress | Gets the first address to be used for the session (BSTR).
get_NumAddresses | Gets the number of addresses to be used for the session (ULONG).
get_Ttl | Gets the time to live scope for transmissions on the addresses (BYTE).
get_BandwidthModifier | Gets the bandwidth modifier, which is a single alphanumeric word giving the meaning of the bandwidth figure (BSTR). The two modifiers defined are CT (Conference Total) and AS (Application Specific Maximum).
get_Bandwidth | Get bandwidth value.
SetAddressInfo | Sets address information.
SetBandwidthInfo | Sets the bandwidth value.
SetEncryptionKey | Sets the encryption key needed to decrypt the session or an indication to a mechanism to obtain a usable key by external means (BSTR). (Not implemented for Windows NT 5 beta 1.)
GetEncryptionKey | Gets the encryption key. (Not implemented for Windows NT 5 beta 1.)


ITConnection::get_NetworkType

[This is preliminary documentation and subject to change.]

Gets the network type.

HRESULT get_NetworkType(
  BSTR *ppNetworkType
);

Parameters

ppNetworkType
[out] Network type.

Return Values

TBD


ITConnection::put_NetworkType

[This is preliminary documentation and subject to change.]

Sets the network type.

HRESULT put_NetworkType(
  BSTR pNetworkType
);

Parameters

pNetworkType
[in] Network type.

Return Values

TBD


ITConnection::get_AddressType

[This is preliminary documentation and subject to change.]

Gets the address type.

HRESULT get_AddressType(
  BSTR *ppAddressType
);

Parameters

ppAddressType
[out] Address type.

Return Values

TBD


ITConnection::put_AddressType

[This is preliminary documentation and subject to change.]

Sets the Address type.

HRESULT put_AddressType(
  BSTR pAddressType
);

Parameters

pAddressType
[in] Address type.

Return Values

TBD


ITConnection::get_StartAddress

[This is preliminary documentation and subject to change.]

Gets the first address to be used for the session (BSTR).

HRESULT get_StartAddress(
  BSTR *ppStartAddress
);

Parameters

ppStartAddress
[out] Starting address.

Return Values

TBD


ITConnection::get_NumAddresses

[This is preliminary documentation and subject to change.]

Gets the number of addresses to be used for the session (ULONG).

HRESULT get_NumAddresses(
  ULONG *pNumAddresses
);

Parameters

pNumAddresses
[out] Number of addresses for session.

Return Values

TBD


ITConnection::get_Ttl

[This is preliminary documentation and subject to change.]

Gets the time to live scope for transmissions on the addresses (BYTE).

HRESULT get_Ttl(
  BYTE *pTtl
);

Parameters

pTtl
[out] Time to live scope.

Return Values

TBD


ITConnection::get_BandwidthModifier

[This is preliminary documentation and subject to change.]

Gets the bandwidth modifier, which is a single alphanumeric word giving the meaning of the bandwidth figure (BSTR). The two modifiers defined are CT (Conference Total) and AS (Application Specific Maximum).

HRESULT get_BandwidthModifier(
  BSTR *ppModifier
);

Parameters

ppModifier
[out] Bandwidth modifier.

Return Values

TBD


ITConnection::get_Bandwidth

[This is preliminary documentation and subject to change.]

Gets the bandwidth value.

HRESULT get_BandwidthModifier(
  ULONG *pBandwidth
);

Parameters

pBandwidth
[out] Bandwidth value.

Return Values

TBD


ITConnection::SetAddressInfo

[This is preliminary documentation and subject to change.]

Sets address information.

HRESULT SetAddressInfo(
  BSTR *pStartAddress,
  ULONG NumAddress,
  BYTE Ttl
);

Parameters

pStartAddress
[in] Start address.
NumAddress
[in] Number of addresses to be used for the session.
Ttl
[in] Time to live scope for transmissions on the addresses.

Return Values

TBD


ITConnection::SetBandwidthInfo

[This is preliminary documentation and subject to change.]

Sets the bandwidth information.

HRESULT SetBandwidthInfo(
  ULONG Bandwidth
);

Parameters

Bandwidth
[in] Bandwidth.

Return Values

TBD


ITConnection::SetEncryptionKey

[This is preliminary documentation and subject to change.]

Sets the encryption key needed to decrypt the session or an indication to a mechanism to obtain a usable key by external means (BSTR). (Not implemented for Windows NT 5 beta 1.)

HRESULT SetEncryptionKey(
 BSTR pKeyType
 BSTR *ppKeydata
);

Parameters

pKeyType
[in] Encryption key type.
ppKeydata
[in] Encryption key information.


ITConnection::GetEncryptionKey

[This is preliminary documentation and subject to change.]

Gets the encryption key. (Not implemented for Windows NT 5 beta 1.)

HRESULT GetEncryptionKey(
 BSTR *ppKeyType,
 VARIANT_BOOL *pfValidKeyData,
 BSTR *ppKeydata
);

Parameters

ppKeyType
[out] Pointer to type of encryption key.
pfValidKeyData
[out] Indicates validity of encryption key data.
ppKeydata
[out] Pointer to encryption key data.

Return Values

TBD


ITNotification

[This is preliminary documentation and subject to change.]

This is a mandatory COM interface for the conference blob component. It provides notification of a change in one or more attributes (identified by a Notification Identifier) and the new value.

The interface definition is as follows:

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.
IDispatch Methods | Description
GetTypeInfoCount | Retrieves the number of type information interfaces.
GetTypeInfo | Retrieves the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.
ITNotification Method | Description
ChangeNotification | Notifies the component of a change in an aggregating component property.


ITNotification::ChangeNotification

[This is preliminary documentation and subject to change.]

This method notifies the component of a change in an aggregating component property. NotificationId is the dispatch id of the modified property in the ITConference interface of the aggregating component.

HRESULT ChangeNotification(
  [in] RND_NOTIFICATION_ID NotificationId,
  [in] VARIANT newVal
);

Parameters

NotificationId
[in] Notification Identifier for type of change.
newVal
[in] Variant containing new value for item changed.

Return Values

TBD


About DirectShow Real-Time Transport Protocol

[This is preliminary documentation and subject to change.]

The DirectShow™ Real-Time Transport Protocol (RTP) is a set of Component Object Model (COM) objects, interfaces, and methods that can handle transporting nearly any media type. These methods can be invoked by applications to expose media and controls.

Methods used follow the RTP specifications in RFC 1889 and RFC 1890, as well as the various RTP payload specifications for supported payload handlers.

The following material assumes familiarity with COM, DirectShow, and RTP.

The filters and filter graphs were designed and developed under a joint development agreement with Intel Corporation.


Using DirectShow Real-Time Transport Protocol

[This is preliminary documentation and subject to change.]

Requirements for a DirectShow™-based RTP architecture fall into the following two categories.

DirectShow Requirements

RTP Requirements


DirectShow Requirements

[This is preliminary documentation and subject to change.]

DirectShow provides a well defined architecture for handling all types of multimedia data using abstractions such as filters and pins. Best performance in DirectShow (and in general) is achieved by minimizing both data copies and thread-switches. These attributes served as the primary guidelines in developing an architecture for DirectShow RTP.

An important further optimization is to allow processing of multimedia data in kernel mode. This can be accomplished by using WDM streaming. In order to facilitate this migration of functionality from user to kernel mode, all data processing should be done within the DirectShow model. Thus, RTP packets are carried as DirectShow Media Samples, passed between filters that implement the various functions necessary to support RTP. These filters can later be migrated to the kernel as WDM streaming nodes, leaving proxies in their place to expose control functionality to applications.


RTP Requirements

[This is preliminary documentation and subject to change.]

Several requirements must be met in order to fully support the RTP specification:

  • Multicast Sessions - RTP is frequently used for conferences with a large number of participants broadcasting multimedia data streams on the same multicast group. The active membership (transmitters as opposed to passive receivers) of the conference may change over time. Some members may be of greater interest to viewers than others, such as the conference chair. To support this type of RTP session, it must be possible to dynamically select attendees and speaker priority. It must also be possible to listen to all speakers concurrently.
  • Changing Payload Types - RTP allows a stream's payload type to change mid-stream, with no signaling other than in the PT field of the RTP header. This frequently occurs in response to detection of bandwidth constraints requiring lower data rates (or allowing higher ones), necessitating that different compression algorithms be used. Changing payload types must be accommodated without causing significant breaks in presentation.
  • Stream Mixing - In a large conference, multiple participants may speak simultaneously. It should be possible for such streams to mix both for purposes of reception (performing mixing in PCM form) and for purposes of retransmission (for example, mixing RTP packets directly, with no decompression being performed).
  • New Payload Types - RTP allows for new payload types to be specified. Such payload types often require new payload handlers as well as new codec (coder/decoder) routines. In order to enable development of new payload types, payload handlers should be simple to implement with a minimal set of initial requirements.


DirectShow RTP Architecture

[This is preliminary documentation and subject to change.]

The following topics describe DirectShow RTP architecture.

RTP Source Filter

RTP Render Filter

RTP Demux Filters

RTP Receive Payload Handler (RPH) Filter

RTP Send Payload Handler (SPH) Filter

PCM Mixer Filter

Silence Suppression Filter


RTP Source Filter

[This is preliminary documentation and subject to change.]

This filter acts as a source of RTP packets in a DirectShow filter graph (it is a sink in relation to the network) for a single RTP session. It exposes a single output pin which is of type MEDIATYPE_RTP_Multiple_Stream /MEDIASUBTYPE_RTP_Payload_Mixed, and it delivers both RTP and RTCP data on this pin. This filter performs no processing on the RTP data it receives apart from tracking necessary information for generating RTP Receiver Reports. All RTP packets received are immediately delivered downgraph with no re-ordering or buffering performed.

This filter exposes an application interface for controlling an RTP session. Attributes of this interface include the session description used in generating RTCP SDES reports and the address and port to send RTP streams and RTCP reports. This filter uses DirectShow notifications to indicate asynchronous events such as socket errors and reception of new RTCP reports.


RTP Render Filter

[This is preliminary documentation and subject to change.]

This filter acts as a sink for RTP packets in a DirectShow filter graph (it is a source in relation to the network) for a single stream within an RTP session. It exposes a single input pin that accepts a connection with any pin of major media type MEDIATYPE_RTP_Single_Stream. The payload type (minor type) of any suggested connection is ignored by this filter.

This filter is responsible for generating RTCP Sender Reports. This filter is payload independent, with the exception of the stream clock value which is necessary for accurately generating NTP and RTP timestamp information in sender reports.

This filter exposes an application interface for controlling an RTP session that is very similar to that of the RTP Source filter. This filter also uses DirectShow notifications to indicate asynchronous events such as socket errors and report reception.


RTP Demux Filters

[This is preliminary documentation and subject to change.]

The RTP Demux Filter is used to demultiplex RTP packets received from a multicast conference into separate streams. It also serves as a point of control through which the application can select which streams are important (and thus are rendered) and which are not. This filter exposes a single input pin, which is of type MEDIATYPE_RTP_Multiple_Stream/MEDIASUBTYPE_RTP_Payload_Mixed. It can expose an application-configured number of output pins, each of which is of payload type MEDIATYPE_RTP_Single_Stream/MEDIASUBTYPE_RTP_Payload_XXXX.

Each output pin corresponds to a single sender in an RTP session, which must be transmitting RTP packets whose PT value matches the assigned media subtype of the pin. The quantity of pins and the assignment of each pin to a particular sender are determined by the application.

The number of pins and their media types may only be set when the filter is in a stopped state. However, the assignment of each stream to a particular pin may be changed dynamically.

This solves the problem of changing media types within a particular stream, in that a particular Demux filter could have two different MEDIASUBTYPE_RTP_Payload_XXXX type output pins. For example, one pin might be configured for MEDIASUBTYPE_RTP_Payload_G711 and one for MEDIASUBTYPE_RTP_Payload_G723. Each would be connected to the appropriate RTP Receive Payload Handler (RPH) filter followed by a decoder and other necessary filters. If a sender that was transmitting a stream of type G.711 changed PT to G.723, it would be possible to change the pin. Its RTP packets are delivered to ensure that the packets are given to the correct payload handler. As no reconnection of filters would be necessary, this can be done without stopping the filter graph.

Some pins may be not be assigned to any particular stream. These pins may be used by the application as a pool to dynamically assign the stream to pins. Sporadic speakers in a large conference can then be rendered without forcing allocation of separate codecs and renderers for each speaker. To further support this feature, the RTP Demux filter can be configured to automatically map new streams to available pins with the appropriate media type.

This filter uses DirectShow notifications to indicate to the application when new SSRCs have been arrived. This filter also indicates automatic mapping of new streams to pins and later unmapping (due to timeouts) of streams via the same methods.


RTP Receive Payload Handler (RPH) Filter

[This is preliminary documentation and subject to change.]

RTP Receive Payload Handler exposes a single input pin and a single output pin. The input pin of this filter is of type MEDIATYPE_RTP_Single_Stream/MEDIASUBTYPE_RTP_Payload_XXXX. The output pin of this filter is the corresponding DirectShow media type. Thus, this filter could expose an input pin of major type MEDIATYPE_RTP_Single_Stream, minor type MEDIASUBTYPE_RTP_Payload_H261, while its output pin would be MEDIATYPE_Video, MEDIASUBTYPE_H261. This filter is responsible for reordering and reassembling RTP packets into multimedia buffers.

The RTP RPH filter also places a valid DirectShow timestamp on the buffers based on the RTP and NTP timestamps for this stream. In the absence of sufficient information to generate a valid timestamp (for example., prior to receiving an RTCP sender report (SR) for the stream in question), the samples timestamp is the current value of the DirectShow clock, resulting in immediate rendering.

This filter also may be used to maintain an application-controlled queue of packets, which can buffer for network jitter.

To support hierarchical encodings, the output of the RPH filter must be modified. In particular, band merging cannot be accomplished without proper synchronization of samples from different bands. After a sender report (SR) has been received for any particular band, the corresponding unique DirectShow time can be determined from the RTP timestamp and the NTP time in the report. However, sender reports are carried through unreliable means (typically UDP) and typically arrive several seconds after reception of a stream commences. Rather than wait for SR arrival to occur for all bands in a hierarchically encoded stream, the RPH filter passes RTP timestamp data to the band merging filter. This information is delivered in the DirectShow start timestamp of the associated media sample. After NTP timestamps are received through a RTCP sender report, the associated NTP value is placed in the end timestamp of the media sample. The band merging filter uses the RTP timestamp information to synchronize samples and then timestamps them for immediate playback. When NTP information is available, timestamps are done according to wall clock time, allowing audio/video synchronization. Activating delivery of RTP and NTP timestamps rather than DirectShow timestamps is done with an application interface into the RPH. This interface is intended to be used by a hierarchical encoding manager component, which would also be responsible for connecting the correct PPM to the correct band input pin of a merger filter.


RTP Send Payload Handler (SPH) Filter

[This is preliminary documentation and subject to change.]

The RTP Send Payload Handler Filter exposes a single input pin and a single output pin. The output pin of this filter is of type MEDIATYPE_RTP_Single_Stream/ MEDIASUBTYPE_RTP_Payload_XXXX. The input pin of this filter is of the corresponding media type. This filter is responsible for segmenting multimedia buffers into RTP packets as well as prepending appropriate RTP headers with RTP timestamps.

Certain payload types require special encoding to be fragmented correctly by a payload handler. Typically, an extended bitstream is attached to the end of the multimedia data. To indicate to a codec that this alternative encoding is necessary, the SPH filter will expose input pins with a unique media type. For example, rather than exposing an input pin of type MEDIATYPE_Video/MEDIASUBTYPE_H263, the filter would expose one of type MEDIATYPE_Video/MEDIASUBTYPE_H263_Extended. Encoders unable to support this extended bitstream (which thus cannot be used to produce legal RTP H.263 streams) would have to be used with the generic RTP SPH, which accepts any payload type and subtype.


PCM Mixer Filter

[This is preliminary documentation and subject to change.]

The audio mixer will accept input formats of WAVE_FORMAT_PCM and WAVE_FORMAT_MULAW. The only output format is WAVE_FORMAT_PCM. This means that the mixer will do a minimal translation from muLaw to PCM.

It can mix 8-bit or 16-bit samples. When the input format is WAVE_FORMAT_PCM, the input and output sample sizes must be the same. If the input format is WAVE_FORMAT_MULAW the output sample size can be 8 or 16 bits.

The mixer can mix with any buffer size or sampling frequency. The only restriction is that the buffer size and frequency must be the same for all inputs and output. The only exception is when the input format is muLaw and the output sample size is 16 bits. Then the output buffer size must be exactly twice the input buffer size.

The mixer operates on a timed basis and thus does not wait for input to all its sources in order to mix. Using a delay that is determined by the buffer size, bits per sample, and sampling frequency, the mixer will periodically check all its inputs for data, then mix and deliver whatever data is available. When no data is available on any input, the mixer will deliver artificial silence.


Silence Suppression Filter

[This is preliminary documentation and subject to change.]

This filter is used to detect when silence is being captured by the audio capture filter. When detected, this filter pauses a graph. This allows the SPH filter to be able to properly indicate talk spurts when packetizing audio samples.

The filter will accept PCM audio at any sampling frequency, with either 8 or 16 bits per sample. Although the filter will accept stereo data, it is implemented such that it would only consider the left channel for silence detection. The filter also needs to signal downstream filters of the beginning of a talk spurt so that they can set bits in the RTP header correctly.

The filter determines the peak and average over the sample buffers passed to it. Then, based on the EnergyFunction property, it will test one of these values against the EchoThreshold plus a "running average" to determine if it is silent. If the buffer energy is greater than this sum for RunningAverageTime then the running average is increased by AverageIncrementor. If the buffer energy falls below the running average (without adding the EchoThreshold), the running average is set to the energy of that buffer. In this way the filter will gradually adapt to background noise.

To prevent clipping, the filter will play a user-defined number of samples before and after the nonsilent data. That is, if the filter has been processing silent buffers and a nonsilent buffer is detected, the filter will deliver buffers processed prior to delivering the nonsilent buffer totaling an elapsed time of PreplayBufferTime . If the filter has been processing nonsilent buffers and it detects a silent buffer, it will deliver a silence of length PostplayBufferTime before it stops delivering silent buffers.


DirectShow Real-Time Transport Protocol Reference

[This is preliminary documentation and subject to change.]

The following material details Component Object Model (COM) interfaces and methods exposed for creating and processing DirectShow™ Real-Time Transport Protocol (RTP) packets. Familiarity with COM, DirectShow, and RTP is assumed.

Categories | Description
DirectShow RTP Network Filters | Forwards RTP packets from the network to the Demux filters, and from the RTP SPH filter to the network.
RTP Demux Filter | Demultiplexes RTP packets received from a multicast conference into separate streams.
RTP Receive Payload Handler | Reorders and reassembles received RTP packets into multimedia buffers.
RTP Send Payload Handler Filter | Segments multimedia buffers into RTP packets to be sent.
Silence Suppression | Detects silence in an audio stream and only delivers packets that are nonsilent.
H26X Video Control Interfaces | Sets decoder brightness, contrast, and saturation, and encoder frame size and quality.


DirectShow RTP Network Filters

[This is preliminary documentation and subject to change.]

The DirectShow network filters are responsible from forwarding RTP packets from the network to the Demux filters, and from the RTP SPH filter to the network.

Constants and Structures

RTP Network Filter Constants

Interaces

IRTPStream Configures the incoming RTP stream associated with the Source filter.


RTP Network Filter Constants

[This is preliminary documentation and subject to change.]

CLSID_RTPRenderFilter

CLSID_RTPRenderFilterProperties

CLSID_RTPSourceFilter

CLSID_RTPSourceFilterProperties

IID_IRTPStream


IRTPStream

[This is preliminary documentation and subject to change.]

This interface is used to configure the RTP stream.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IRTPStream Methods | Description
GetAddress | Get RTP address and length of address.
SetAddress | Set RTP address.
GetMulticastScope | Get multicast scope.
SetMulticastScope | Set multicast scope.
SetQualityOfService | Set details of desired quality of service (QOS).
GetQOSstate | Get QOS state.
SetQOSstate | Set QOS state.
GetMulticastLoopBack | Get multicast loopback.
SetMulticastLoopBack | Set multicast loopback.


IRTPStream::GetAddress

[This is preliminary documentation and subject to change.]

Get RTP address and length of address.

GetAddress(
  LPBYTE pRtpAddr,
  LPDWORD pdwRtpAddrLen
);

Parameters

pRtpAddr
Long pointer to RTP address.
pdwRtpAddrLen
Pointer to DWORD representation of RTP address length.

Return Values

TBD


IRTPStream::SetAddress

[This is preliminary documentation and subject to change.]

Set RTP address.

SetAddress(
  LPBYTE pRtpAddr,
  DWORD dwRtpAddrLen
);

Parameters

pRtpAddr
Long pointer to RTP address.
dwRtpAddrLen
DWORD representation of RTP address length.

Return Values

TBD


IRTPStream::GetMulticastScope

[This is preliminary documentation and subject to change.]

Get multicast scope.

GetMulticastScope(
  LPDWORD pdwMulticastScope
);

Parameters

pdwMulticastScope
Long pointer to DWORD representation of multicast scope.

Return Values

TBD


IRTPStream::SetMulticastScope

[This is preliminary documentation and subject to change.]

Set multicast scope.

SetMulticastScope(
  DWORD dwMulticastScope
);

Parameters

dwMulticastScope
DWORD representation of multicast scope.

Return Values

TBD


IRTPStream::SetQualityOfService

[This is preliminary documentation and subject to change.]

Set details of desired quality of service.

SetQualityOfService(
  QOS *pQOS
);

Parameters

pQOS
Pointer to QOS structure describing desired quality of service.

Return Values

TBD


IRTPStream::GetQOSstate

[This is preliminary documentation and subject to change.]

Get QOS state.

GetQOSstate(
  DWORD *pdwQOSstate
);

Parameters

pdwQOSstate
Pointer to DWORD representation of QOS state.

Return Values

TBD


IRTPStream::SetQOSstate

[This is preliminary documentation and subject to change.]

Set QOS state.

SetQOSstate(
  DWORD dwQOSstate
);

Parameters

dwQOSstate
DWORD representation of QOS state.

Return Values

TBD


IRTPStream::GetMulticastLoopBack

[This is preliminary documentation and subject to change.]

Get multicast loopback.

GetMulticastLoopBack(
  DWORD *pdwMulticastLoopBack
);

Parameters

pdwMulticastLoopBack
TBD

Return Values

TBD


IRTPStream::SetMulticastLoopBack

[This is preliminary documentation and subject to change.]

Set multicast loopback.

SetMulticastLoopBack(
  DWORD dwMulticastLoopBack
);

Parameters

dwMulticastLoopBack
TBD

Return Values

TBD


RTP Demux Filter

[This is preliminary documentation and subject to change.]

This filter is used to demultiplex RTP packets received from a multicast conference into separate streams. It also serves as a point through which the application may control which streams are important (and thus are rendered) and which are not. This filter exposes a single input pin, which is of type MEDIATYPE_RTP_Multiple_Stream/MEDIASUBTYPE_RTP_Payload_Mixed. It can expose an application-configured number of output pins, each of which is of payload type MEDIATYPE_RTP_Single_Stream/MEDIASUBTYPE_RTP_Payload_XXXX.

Each output pin corresponds to a single sender in an RTP session, which must be transmitting RTP packets whose PT value matches the assigned media subtype of the pin. The quantity of pins and the assignment of each pin to a particular sender are determined by the application.

The number of pins and their media types may only be set when the filter is in a stopped state. However, the assignment of each stream to a particular pin may be changed dynamically. This solves the problem of changing media types within a particular stream, in that a particular Demux filter could have two MEDIASUBTYPE_RTP_Payload_XXXX type output pins -- one configured for MEDIASUBTYPE_RTP_Payload_G711 and one for MEDIASUBTYPE_RTP_Payload_G723. Each would be connected to the appropriate RTP RPH filter followed by a decoder and other necessary filters. If a sender transmitting a stream of type G.711 changed PT to G.723, it would be possible to change the pin. The RTP packets are delivered to ensure that the packets are given to the correct payload handler. As no reconnection of filters would be necessary, this could be done without stopping the filter graph.

It is possible for an application to leave some pins unassigned to any particular stream. These pins may then be used by the application as a pool to dynamically assign streams to pins. This allows sporadic speakers in a large conference to be rendered without forcing allocation of separate codecs and renderers for each speaker. To further support this feature, the RTP Demux filter can be configured to automatically map new streams to available pins with the appropriate media type.

This filter uses DirectShow™ notifications to indicate to the application when new SSRCs have been arrived. This filter also indicates automatic mapping of new streams to pins and later indicates unmapping (due to timeouts) of streams via the same methods.

Structures

RTP Demux Constants

Interfaces

IEnumSSRCs | Queries the SSRCs currently being tracked by the RTP Demux filter.
IRTPDemuxFilter | Initializes and controls the Intel RTP Demux filter.


RTP Demux Constants

[This is preliminary documentation and subject to change.]

CLSID_IntelRTPDemux

CLSID_IntelRTPDemuxPropertyPage


IEnumSSRCs

[This is preliminary documentation and subject to change.]

This interface is used to query the list of SSRCs the RTP Demux filter is currently tracking. It is returned by IRTPDemuxFilter::EnumSSRCsIRTPDemuxFilter::EnumSSRCs and is based on IEnumXXXX.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IEnumSSRCs Methods | Description
Next | Gets the next specified number of elements in the enumeration sequence.
Skip | Skips over the next specified number of elements in the enumeration sequence.
Reset | Resets to beginning of enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.


IEnumSSRCs::Next

[This is preliminary documentation and subject to change.]

Gets the next specified number of elements in the enumeration sequence.

HRESULT Next(
  ULONG cSSRCs,
  DWORD *pdwSSRCs,
  ULONG *pcFetched
);

Parameters

cSSRCs
Places cSSRCs many pins in the array.
pdwSSRCs
Pointer to array of size cSSRCs.
pcFetched
Actual count passed.

Return Values

S_OK
If the number of elements supplied is cSSRCs.
S_FALSE
If the number of elements supplied is not cSSRCs.


IEnumSSRCs::Skip

[This is preliminary documentation and subject to change.]

Skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG cSSRCs
);

Parameters

cSSRCs
Number of elements to skip.

Return Values

S_OK
If the number of elements skipped is cSSRCs.
S_FALSE
If the number of elements skipped is not cSSRCs.


IEnumSSRCs::Reset

[This is preliminary documentation and subject to change.]

Resets to beginning of enumeration sequence.

HRESULT Reset();

Parameters

None.

Return Values

S_OK


IEnumSSRCs::Clone

[This is preliminary documentation and subject to change.]

Creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumSSRCs **ppEnum
);

Parameters

ppEnum
Pointer to cloned enum.

Return Values

E_INVALIDARG
ppEnum is not valid.
E_OUTOFMEMORY
Insufficient memory available.
E_UNEXPECTED
Failed for unknown reasons.


IRTPDemuxFilter

[This is preliminary documentation and subject to change.]

This interface is used to initialize and control the Intel RTP Demux filter. It includes methods to control the mapping of SSRCs to pins and to set pin media types. This interface is implemented by the RTP Demux filter, and must be used by the application for both filter setup (pre-connection to other filters) and dynamic control.

See RTP Demux Filter for more detailed information on the function of this filter.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IRTPDemuxFilter Methods | Description
EnumSSRCs | Returns an SSRC enumerator.
GetPinInfo | Returns all the information available for a particular output pin.
GetSSRCInfo | Retrieves information about a particular SSRC.
MapSSRCToPin | Configures the SSRC that will be delivered on a particular pin.
SetPinCount | Configures how many output pins will be exposed by the RTP Demux filter.
SetPinTypeInfo | Configures the payload type accepted and the minor media type exposed by a particular output pin of the RTP Demux filter.
SetPinMode | Activates automatic mapping for a pin.
SetPinSourceTimeout | Sets the amount of time that must pass before a stream associated with a particular pin will be unmapped.
UnmapPin | Unmaps any stream that is currently mapped to a particular pin.
UnmapSSRC | Unmaps a particular SSRC from the pin it is being delivered on.


IRTPDemuxFilter ::EnumSSRCs

[This is preliminary documentation and subject to change.]

Returns an SSRC enumerator, which is used by an application to see what SSRCs the RTP Demux filter currently is aware of and what it is doing with them.

HRESULT EnumSSRCs(
  IEnumSSRCs **ppIEnumSSRCs
);

Parameters

ppIEnumSSRCs
Pointer to SSRC enumerator.

Return Values

E_POINTER
The ppIEnumSSRCs parameter is not a valid pointer.
NOERROR
Successfully returned an enumerator for the SSRCs currently detected by this filter.


IRTPDemuxFilter ::GetPinInfo

[This is preliminary documentation and subject to change.]

Returns all the information available for a particular output pin.

HRESULT GetPinInfo(
  IPin *pIPin,
  DWORD *pdwSSRC,
  BYTE *pbPT,
  BOOL *pbAutoMapping,
  DWORD *pdwTimeout
);

Parameters

pIPin
Pointer to the IPin interface of an output pin of this filter.
pdwSSRC
Pointer to a DWORD to store the SSRC of the stream currently mapped to this pin. A value of 0 indicates that this pin is not mapped to any stream.
pbPT
Pointer to a BYTE in which the current PT value being accepted by this pin is placed.
pbAutoMapping
Pointer to a boolean indicating whether this is an automapping pin.
pdwTimeout
Pointer to a DWORD that indicates how many milliseconds may pass for a SSRC before it is considered stale and may automatically be replaced by a fresh SSRC. If pbAutoMapping is FALSE, then this parameter will always be set to zero.

Return Values

TDB


IRTPDemuxFilter ::GetSSRCInfo

[This is preliminary documentation and subject to change.]

This method is used to retrieve information about a particular SSRC that is available to the RTP Demux filter. This includes the PT value of the SSRC and what pin, if any, it is currently being delivered on.

HRESULT GetSSRCInfo(
  DWORD dwSSRC,
  BYTE *pbPT,
  IPin **ppIPin
);

Parameters

dwSSRC
The SSRC that information is being requested for.
pbPT
Current PT value.
ppIPin
Current pin that the indicated SSRC is mapped to. If not mapped to any pin, this is NULL.

Return Values

E_HANDLE
The ppIPin parameter is not a valid pointer.
E_INVALIDARG
No such SSRC has been detected.
E_POINTER
The pbPT parameter is not a valid pointer.
NOERROR
Successfully returned the information available for this SSRC.


IRTPDemuxFilter ::MapSSRCToPin

[This is preliminary documentation and subject to change.]

This method is used to configure the SSRC that will be delivered on a particular pin. This method may be called for any output pin of the RTP Demux filter at any time. If a pin previously had an SSRC mapped to it, the new SSRC value will override it, causing the previously mapped SSRC to no longer be rendered.

HRESULT MapSSRCToPin(
  DWORD dwSSRC,
  IPin *pIPin
);

Parametrs

dwSSRC
SSRC of the stream to output on this pin.
pIPin
Pointer to an IPin interface to which the indicated SSRC is mapped. If NULL, the SSRC will be mapped to the first available (unmapped) pin whose subtype matches the PT of the SSRC in question.

Return Values

E_HANDLE
The ppIPin parameter is not a valid pointer.
E_INVALIDARG
No such SSRC has been detected.
E_POINTER
The pbPT parameter is not a valid pointer.
NOERROR
Successfully returned the information available for this SSRC.


IRTPDemuxFilter ::SetPinCount

[This is preliminary documentation and subject to change.]

This method is used to configure how many output pins will be exposed by the RTP Demux filter. This method may only be called while this filter is in a stopped state.

HRESULT SetPinCount(
  DWORD dwPinCount
);

Parameters

dwPinCount
The number of output pins that this filter should expose. If this value is less than the current number of output pins, then available (unmapped) output pins will be removed. If this value is greater than the current number of output pins, new pins will be allocated.

Return Values

E_INVALIDARG
The indicated pin count is less than the number of currently connected output pins. Pins may only be removed when they are not connected.
VFW_E_NOT_STOPPED
This method may only be called when the filter is in the stopped state.
NOERROR
The output pin count of this filter is successfully set.


IRTPDemuxFilter ::SetPinTypeInfo

[This is preliminary documentation and subject to change.]

This method is used to configure the payload type accepted and the minor media type exposed by a particular output pin of the RTP Demux filter. The major type for all output pins of the RTP Demux filter is always defined to be RTP_Single_Stream. This method may only be called on pins which are currently not connected.

HRESULT SetPinTypeInfo(
  IPin *pIPin,
  BYTE bPT,
  GUID gMinorType
);

Parameters

pIPin
The pin to change the subtype of.
bPT
Expected payload type for this pin.
gMinorType
Minor type to assign to indicated pin. The minor type must be a legal value matching one of the entries on the list of valid DirectShow RTP minor types, or GUID_NULL if bPT contains the value of a well known RTP PT specification.

Return Values

E_HANDLE
The pin indicated by pIPin does not exist or is not an output pin.
VFW_E_ALREADY_CONNECTED
The pin indicated by pIPin is currently connected. (Pins must not be connected for their media type to be changed.)
VFW_E_TYPE_NOT_ACCEPTED
The payload type indicated by bPT is not within the legal range of RTP payload types, which is 0 - 127. If gMinorType is passed in as MEDIASUBTYPE_NULL, then this result code will occur if bPT is any PT value which does not have a static payload type value assigned to it.
NOERROR
The minor type and the expected payload type for the indicated pin is successfully set.


IRTPDemuxFilter ::SetPinMode

[This is preliminary documentation and subject to change.]

This method is used to activate automatic mapping for a pin. A pin that has been set for automatic mapping will be assigned the first unmapped SSRC that is delivered to the RTP Demux filter that matches the minor type of the pin. Pins in this mode will continue to render that SSRC until the timeout value indicated in SetPinSourceTimeout passes without reception of any more RTP packets. At that time, the SSRC will be unmapped and the pin will map the next available packet.

HRESULT SetPinMode(
  IPin *pIPin,
  BOOL bAutomatic
);

Parameters

pIPin
Pointer to the IPin interface of an output pin of this filter.
bAutomatic
Specifies whether this pin should be in automatic mapping mode.

Return Values

E_HANDLE
The pin indicated by pIPin does not exist or is not an output pin.
NOERROR
The pin mode is successfully set.


IRTPDemuxFilter ::SetPinSourceTimeout

[This is preliminary documentation and subject to change.]

This method is used to set the amount of time that must pass before a stream associated with a particular pin will be unmapped. This method may be called for any output pin of the RTP Demux filter at any time.

HRESULT SetPinSourceTimeout(
  IPin *pIPin,
  DWORD dwMilliseconds
);

Parameters

pIPin
Pointer to the IPin interface of an output pin of this filter.
dwMilliseconds
The amount of time, in milliseconds allowed to elapse after the last RTP packet from a particular source has been delivered through this pin before the source is unmapped. A value of INFINITE, as defined in WINBASE.H, means that a particular stream will remain mapped to a pin until either the pin is destroyed, the stream PT value changes, or the application manually changes the stream association. This value must be at least 100 milliseconds. The clock mechanisms available in Windows® have too much jitter to make finer granularity timeouts feasible.

Return Values

E_HANDLE
The pin indicated by pIPin does not exist or is not an output pin.
NOERROR
Successfully set the pin mode.


IRTPDemuxFilter ::UnmapPin

[This is preliminary documentation and subject to change.]

This method may be used to unmap any stream that is currently mapped to a particular pin.

HRESULT UnmapPin(
  IPin *pIPin,
  DWORD *pdwSSRC
);

Parameters

pIPin
The pin to unmap.
pdwSSRC
Upon success, the SSRC that had previously been mapped to this pin is placed in pdwSSRC as a return value. Upon failure, this value is set to NULL.

Return Values

E_HANDLE
Invalid pIPin parameter.
E_POINTER
Invalid pdwSSRC parameter.
E_UNEXPECTED
The pin in question is not currently mapped to any stream.
NOERROR
Pin is successfully unmapped.


IRTPDemuxFilter ::UnmapSSRC

[This is preliminary documentation and subject to change.]

This method is used to unmap a particular SSRC from the pin it is being delivered on.

HRESULT UnmapSSRC(
  DWORD dwSSRC,
  IPin **ppIPin
);

Parameters

dwSSRC
SSRC value to be unmapped.
ppIPin
Pin which this SSRC had been mapped to.

Return Values

E_INVALIDARG
The RTP Demux filter has no record of the SSRC in question .
E_POINTER
Invalid ppIPin parameter.
E_UNEXPECTED
The SSRC in question is not currently mapped to any pin.
NOERROR
This SSRC is successfully unmapped.


RTP Receive Payload Handler

[This is preliminary documentation and subject to change.]

This filter is responsible for reordering and reassembling RTP packets into multimedia buffers. It also places a valid DirectShow timestamp on the buffers. See RTP Receive Payload Handler (RPH) Filter for more detailed information.

Structures and Constants

Class IDs

Interfaces

IRTPRPHFilter | This interface is used by the application to initialize and control the RTP Receive Payload Handler filter.
IRPHH26XSettings | TBD


Class IDs

[This is preliminary documentation and subject to change.]

CLSID_INTEL_RPHH26X

CLSID_INTEL_RPHAUD

CLSID_INTEL_RPHGENA

CLSID_INTEL_RPHGENV

CLSID_INTEL_RPHAUD_PROPPAGE

CLSID_INTEL_RPHGENA_PROPPAGE

CLSID_INTEL_RPHGENV_PROPPAGE

CLSID_INTEL_RPHH26X_PROPPAGE

CLSID_INTEL_RPHH26X1_PROPPAGE


IRTPRPHFilter

[This is preliminary documentation and subject to change.]

This interface is used by the application to initialize and control the RTP Receive Payload Handler filter.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IRTPRPHFilter Methods | Description
OverridePayloadType | Set a new RTP payload type to be compared with the PT field in the RTP packet header.
GetPayloadType | Get the RTP payload type which is in the PT field in the RTP packet header.
SetMediaBufferSize | Set the size for the reassembled media data buffers.
GetMediaBufferSize | Get the size for the reassembled media data buffers.
SetOutputPinMediaType | Set the media type of the output pin.
GetOutputPinMediaType | Get the media type of the output pin.
SetTimeoutDuration | Set the duration of the time periods in which to queue reordered and reassembled buffers.
GetTimeoutDuration | Get the duration of the time periods in which to queue reordered and reassembled buffers.


IRTPRPHFilter::OverridePayloadType

[This is preliminary documentation and subject to change.]

Set a new RTP payload type to be compared with the PT field in the RTP packet header. This overrides the default (static or dynamic) payload type determined by the handler. Can be used for such cases as setting negotiated dynamic payload types, setting a payload type for a generic handler, or overriding static defined payload types for specialized data. To be used at initialization time only.

HRESULT OverridePayloadType(
  BYTE bPayloadType
);

Parameters

bPayloadType
[in] The payload type identifier which will be verified in the RTP header.

Return Values

E_INVALIDARG
The bPayloadType value cannot be used (out of range).
NOERROR
The bPayloadType value will be used as the RTP payload type.


IRTPRPHFilter::GetPayloadType

[This is preliminary documentation and subject to change.]

Get the RTP payload type which is in the PT field in the RTP packet header.

HRESULT GetPayloadType(
  BYTE *lpbPayloadType
);

Parameters

lpbPayloadType
[out] Pointer to the variable which will be initialized with the current payload type identifier.

Return Values

E_POINTER
The lpbPayloadType is not a valid pointer.
NOERROR
The RTP payload type is returned successfully.


IRTPRPHFilter::SetMediaBufferSize

[This is preliminary documentation and subject to change.]

Set the size for the reassembled media data buffers. This reflects the maximum expected size of a media sample to be produced by the RPH. If this value is not set, a default value will be chosen based on the media type of the filter. To be used at initialization time only.

HRESULT SetMediaBufferSize(
  DWORD dwMaxMediaBufferSize
);

Parameters

dwMaxMediaBufferSize
[in] Size of the reassembled media data buffers.

Return Values

E_OUTOFMEMORY
The buffer size requested cannot be satisfied due to memory constraints.
NOERROR
The media buffer size has been set successfully.


IRTPRPHFilter::GetMediaBufferSize

[This is preliminary documentation and subject to change.]

Get the size for the reassembled media data buffers.

HRESULT GetMediaBufferSize(
  LPDWORD lpdwMaxMediaBufferSize
);

Parameters

lpdwMaxMediaBufferSize
[out] Pointer to size of the reassembled media data buffers.

Return Values

TDB


IRTPRPHFilter::SetOutputPinMediaType

[This is preliminary documentation and subject to change.]

Set the media type of the output pin. To be used at initialization time only. Should be coordinated with OverridePayloadType.

HRESULT SetOutputPinMediaType(
  AM_MEDIA_TYPE *lpMediaPinType
);

Parameters

lpMediaPinType
[in] The DirectShow media type to which the output pin should be set. Generally for use with a generic payload handler.

Return Values

VFW_E_ALREADY_CONNECTED
The output pin is already connected.
VFW_E_INVALIDSUBTYPE
The media type indicated by MediaPinType does not match the list of accepted values by this filter. Minor types are defined for all RTP fixed payload types and for each possible dynamic payload type value.
NOERROR
The minor media type of the output pin has been set successfully.


IRTPRPHFilter::GetOutputPinMediaType

[This is preliminary documentation and subject to change.]

Get the media type of the output pin.

HRESULT GetOutputPinMediaType(
  AM_MEDIA_TYPE **ppMediaPinType
);

Parameters

ppMediaPinType
[out] Pointer to media type to which the output pin is set.

Return Values

TDB


IRTPRPHFilter::SetTimeoutDuration

[This is preliminary documentation and subject to change.]

Set the duration of the time periods in which to queue reordered and reassembled buffers. If these values are not set at initialization time, default values will be chosen based on the media type of the filter. Once either duration expires, any buffers currently held by the RPH filter will be flushed down the graph. These durations are used to induce some buffering to alleviate jitter and latency problems in the network.

HRESULT SetTimeoutDuration(
  DWORD dwDejitterTime,
  DWORD dwLostPacketTime
);

Parameters

dwDejitterTime
[in] Duration in milliseconds that any one buffer may be queued.
dwLostPacketTime
[in] Duration in milliseconds before a packet is presumed lost.

Return Values

E_INVALIDARG
One or both of the timeout durations specified is zero.
NOERROR
The timeout durations have been set successfully.


IRTPRPHFilter::GetTimeoutDuration

[This is preliminary documentation and subject to change.]

Get the duration of the time periods in which to queue reordered and reassembled buffers.

HRESULT GetTimeoutDuration(
  LPDWORD lpdwDejitterTime,
  LPDWORD lpdwLostPacketTime
);

Parameters

lpdwDejitterTime
[out] Pointer to duration in milliseconds that any one buffer may be queued.
lpdwLostPacketTime
[out] Pointer to duration in milliseconds before a packet is presumed lost.

Return Values

E_POINTER
One or both pointers is not valid.
NOERROR
The timeout durations have been returned successfully.


IRPHH26XSettings

[This is preliminary documentation and subject to change.]

TBD

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IRPHH26XSettings Methods | Description
SetCIF | TBD
GetCIF | TBD


IRPHH26XSettings::SetCIF

[This is preliminary documentation and subject to change.]

TBD

HRESULT SetCIF(
  BOOL bCIF
);

Parameters

bCIF
[in] TRUE if CIF, FALSE if QCIF.

Return Values

TDB


IRPHH26XSettings::GetCIF

[This is preliminary documentation and subject to change.]

TBD

HRESULT GetCIF(
  BOOL *lpbCIF
);

Parameters

lpbCIF
[out] TRUE if CIF, FALSE if QCIF.

Return Values

TDB


RTP Send Payload Handler Filter

[This is preliminary documentation and subject to change.]

This filter is responsible for segmenting multimedia buffers into RTP packets as well as prepending appropriate RTP headers with RTP timestamps.

For more detailed information, please see RTP Send Payload Handler (SPH) Filter.

RTP Send Payload Handler Filter Interfaces | Description
IRTPSPHFilter | RTP Send Payload handler.

Class IDs

CLSID_INTEL_SPHH26X

CLSID_INTEL_SPHAUD

CLSID_INTEL_SPHGENA

CLSID_INTEL_SPHGENV

CLSID_INTEL_SPHAUD_PROPPAGE

CLSID_INTEL_SPHGENA_PROPPAGE

CLSID_INTEL_SPHGENV_PROPPAGE

CLSID_INTEL_SPHH26X_PROPPAGE


IRTPSPHFilter

[This is preliminary documentation and subject to change.]

RTP Send Payload handler.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IRTPSPHFilter Methods | Description
OverridePayloadType | Sets a new RTP payload type for the PT field in the RTP packet header.
GetPayloadType | Get the RTP payload type that is to be used for the PT field in the RTP packet header.
SetMaxPacketSize | Set the maximum packet size for fragmentation of data.
GetMaxPacketSize | Gets the maximum packet size for fragmentation of data.
SetOutputPinMinorType | Set the minor media type of the output pin.
GetOutputPinMinorType | Get the minor media type of the output pin.
SetInputPinMediaType | Set the minor media type of the input pin.
GetInputPinMediaType | Get the minor media type of the input pin.


IRTPSPHFilter::OverridePayloadType

[This is preliminary documentation and subject to change.]

Set a new RTP payload type for the PT field in the RTP packet header. This overrides the default (static or dynamic) payload type determined by the handler. Can be used for such cases as setting negotiated dynamic payload types, setting a payload type for a generic handler, or overriding static defined payload types for specialized data. To be used at initialization time only.

HRESULT OverridePayloadType(
  BYTE bPayloadType
);

Parameters

bPayloadType
[in] The payload type identifier which will be used in the RTP header.

Return Values

E_INVALIDARG
The bPayloadType value is invalid or out of range.
NOERROR
The bPayloadType value will be used as the RTP payload type.


IRTPSPHFilter::GetPayloadType

[This is preliminary documentation and subject to change.]

Get the RTP payload type that is to be used for the PT field in the RTP packet header.

HRESULT GetPayloadType(
  BYTE *lpbPayloadType
);

Parameters

lpbPayloadType
[out] Pointer to the variable which will be initialized with the current payload type identifier.

Return Values

E_POINTER
The lpbPayloadType is not a valid pointer.
NOERROR
The RTP payload type is returned successfully.


IRTPSPHFilter::SetMaxPacketSize

[This is preliminary documentation and subject to change.]

Set the maximum packet size for fragmentation of data. An overall maximum is set at initialization time only. SetMaxPacketSize can be called subsequently to set smaller packets sizes as desired by the application.

HRESULT SetMaxPacketSize(
  DWORD dwMaxPacketSize
);

Parameters

dwMaxPacketSize
[in] The maximum RTP packet size that will be produced.

Return Values

E_INVALIDARG
The packet size requested is larger than the initial maximum setting.
NOERROR
The maximum packet size has been set successfully.


IRTPSPHFilter::GetMaxPacketSize

[This is preliminary documentation and subject to change.]

Gets the maximum packet size for fragmentation of data.

HRESULT GetMaxPacketSize(
  LPDWORD lpdwMaxPacketSize
);

Parameters

lpdwMaxPacketSize
[out] Pointer to the maximum RTP packet size that will be produced.

Return Values

TDB


IRTPSPHFilter::SetOutputPinMinorType

[This is preliminary documentation and subject to change.]

Set the minor media type of the output pin. To be used at initialization time only. Should be coordinated with OverridePayloadType.

HRESULT SetOutputPinMinorType(
  GUID gMinorType
);

Parameters

gMinorType
[in] The media type to which the output pin should be set.

Return Values

VFW_E_ALREADY_CONNECTED
The output pin is already connected.
VFW_E_INVALIDSUBTYPE
The media type indicated by gMinorType does not match the list of accepted values by this filter. Minor types are defined for all RTP fixed payload types and for each possible dynamic payload type value.
NOERROR
The minor media type of the output pin has been set successfully.


IRTPSPHFilter::GetOutputPinMinorType

[This is preliminary documentation and subject to change.]

Set the minor media type of the output pin.

HRESULT GetOutputPinMinorType(
  GUID *lpgMinorType
);

Parameters

lpgMinorType
[out] Pointer to the current minor media type for output pin.

Return Values

TBD


IRTPSPHFilter::SetInputPinMediaType

[This is preliminary documentation and subject to change.]

Set the media type of the output pin.

HRESULT SetInputPinMediaType(
  AM_MEDIA_TYPE *lpMediaPinType
);

Parameters

lpMediaPinType
[in] The media type to which the input pin should be set.

Return Values

VFW_E_ALREADY_CONNECTED
The input pin is already connected.
VFW_E_INVALIDSUBTYPE
The media type indicated by gMinorType does not match the list of accepted values by this filter. Minor types are defined for all RTP fixed payload types and for each possible dynamic payload type value.
NOERROR
The minor media type of the input pin has been set successfully.


IRTPSPHFilter::GetInputPinMediaType

[This is preliminary documentation and subject to change.]

Get the media type of the output pin.

HRESULT GetInputPinMediaType(
  AM_MEDIA_TYPE **ppMediaPinType
);

Parameters

ppMediaPinType
[out] Pointer to the media type of the input pin.

Return Values

TDB


Silence Suppression

[This is preliminary documentation and subject to change.]

A user's impression of audio transmission speed is markedly improved by the suppression of silent packets. The ISilenceSuppressor filter allows a developer to write applications which will not transmit packets during periods in which no sounds are being made.

This filter is used to detect when silence is being captured by the audio capture filter. When detected, this filter pauses a graph. This allows the SPH filter to be able to properly indicate talkspurt indications when packetizing audio samples.

For more detailed information, see Silence Suppression Filter.


ISilenceSuppressor

[This is preliminary documentation and subject to change.]

The Silence Suppressor filter detects silence in an audio stream and only delivers packets that are nonsilent.

Default ValuesdwPreplayBufferTime | 1 (tenths of a second)
dwPostplayBufferTime | 1 (tenths of a second)
dwRunningAverageTime | 5 (tenths of a second)
dwAverageIncrementor | 2 (percent of highest possible peak)
dwEchoThreshold | 8 (percent of highest possible peak)
EnergyFunc | FALSE (false = user peak; true = user average.)

Structures

Silence Suppression Class IDs

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

ISilenceSuppressor Methods | Description
GetPreplayBufferTime | Retrieves time (in tenths of a second) to play prior to delivery of a non-silent buffer.
SetPreplayBufferTime | Sets time (in tenths of a second) to play prior to delivery of a non-silent buffer.
GetPostplayBufferTime | Retrieves time (in tenths of a second) to play after the nonsilent buffer(s).
SetPostplayBufferTime | Sets time (in tenths of a second) to play after the nonsilent buffer(s).
GetRunningAverageTime | Retrieves time interval (in tenths of a second) for calculation of sample buffer average energy.
SetRunningAverageTime | Sets time interval (in tenths of a second) for calculation of sample buffer average energy.
GetAverageIncrementor | Retrieves a pointer to the incrementor for the running average.
SetAverageIncrementor | Sets the incrementor for the running average.
GetEchoThreshold | Retrieves the echo threshold, which is used in defining "silence" for a buffer.
SetEchoThreshold | Sets the echo threshold.
GetUseAverageEnergyFunction | Gets pointer to average energy function.
SetUseAverageEnergyFunction | Sets average energy function.


Silence Suppression Class IDs

[This is preliminary documentation and subject to change.]

CLSID_SilenceSuppressionFilter

CLSID_SilenceSuppressionProperties


ISilenceSuppressor::GetPreplayBufferTime

[This is preliminary documentation and subject to change.]

In order to prevent clipping the filter plays a user defined length of time before and after the nonsilent data. This method retrieves the length of time that will be played prior to the nonsilent buffer(s).

HRESULT GetPreplayBufferTime(
  LPDWORD lpdwPreplayBufferTime
);

Parameters

lpdwPreplayBufferTime
[out] Length of silence (in tenths of a second) to play prior to a non-silent buffer.

Return Values

E_POINTER
The pointer was not valid.
NOERROR
Success.


ISilenceSuppressor::SetPreplayBufferTime

[This is preliminary documentation and subject to change.]

To prevent clipping, the filter plays a user-defined length of time before and after the nonsilent data. This method sets the length of time that will be played prior to the nonsilent buffer or buffers.

HRESULT SetPreplayBufferTime(
  DWORD dwPreplayBufferTime
);

Parameters

dwPreplayBufferTime
[in] Length of silence (in tenths of a second) to play prior to a non-silent buffer.

Return Values

VFW_E_NOT_STOPPED
This method may only be called when the filter is in the stopped state.
NOERROR
Success.


ISilenceSuppressor::GetPostplayBufferTime

[This is preliminary documentation and subject to change.]

To prevent clipping, the filter plays a user-defined length of time before and after the nonsilent data. This method retrieves the length of time that will be played after the nonsilent buffer or buffers.

HRESULT GetPostplayBufferTime(
  LPDWORD lpdwPostplayBufferTime
);

Parameters

lpdwPostplayBufferTime
[out] Length of silence (in tenths of a second) to play prior to a non-silent buffer.

Return Values

E_POINTER
The pointer was not valid.
NOERROR
Success.


ISilenceSuppressor::SetPostplayBufferTime

[This is preliminary documentation and subject to change.]

To prevent clipping, the filter plays a user-defined length of time before and after the nonsilent data. This method sets the length of time that will be played after the nonsilent buffer or buffers.

HRESULT SetPostplayBufferTime(
  DWORD dwPostplayBufferTime
);

Parameters

dwPostplayBufferTime
[in] Length of silence (in tenths of a second) to play after to a non-silent buffer.

Return Values

E_POINTER
The pointer was not valid.
NOERROR
Success.


ISilenceSuppressor::GetRunningAverageTime

[This is preliminary documentation and subject to change.]

To adapt to background noise, the filter uses a running average energy for sample buffers to determine which buffers are silent. This method retrieves the time interval currently being used to calculate the running average energy.

HRESULT GetRunningAverageTime(
  LPDWORD lpdwRunningAverageTime
);

Parameters

lpdwRunningAverageTime
[out] Length of time interval to use in running average calculation.

Return Values

E_POINTER
The pointer was not valid.
NOERROR
Success.


ISilenceSuppressor::SetRunningAverageTime

[This is preliminary documentation and subject to change.]

To adapt to background noise, the filter uses a running average energy for sample buffers to determine which buffers are silent. This method sets the time interval currently being used to calculate the running average energy.

HRESULT SetRunningAverageTime(
  DWORD dwRunningAverageTime
);

Parameters

dwRunningAverageTime
[in] Length of time interval to use in running average calculation.

Return Values

NOERROR
Success.


ISilenceSuppressor::GetAverageIncrementor

[This is preliminary documentation and subject to change.]

If sample buffer energy is greater than EchoThreshold plus running average energy for RunningAverageTime buffers, the running average is increased by AverageIncrementor. This methods retrieves a pointer to AverageIncrementor.

HRESULT GetAverageIncrementor(
  LPDWORD lpdwAverageIncrementor
);

Parameters

lpdwAverageIncrementor
[out] Incrementor for running average.

Return Values

E_POINTER
The pointer was not valid.
NOERROR
Success.


ISilenceSuppressor::SetAverageIncrementor

[This is preliminary documentation and subject to change.]

If sample buffer energy is greater than EchoThreshold plus running average energy for RunningAverageTime buffers, the running average is increased by AverageIncrementor. This methods sets AverageIncrementor.

HRESULT SetAverageIncrementor(
  DWORD dwAverageIncrementor
);

Parameters

dwAverageIncrementor
[in] Incrementor for running average.

Return Values

NOERROR
Success.


ISilenceSuppressor::GetEchoThreshold

[This is preliminary documentation and subject to change.]

Echo threshold is used in conjunction with running average sample buffer energy to determine which buffers are classified as silent. This method retrieves the echo threshold.

HRESULT GetEchoThreshold(
  LPDWORD lpdwEchoThreshold
);

Parameters

lpdwEchoThreshold
[out] Pointer to echo threshold setting.

Return Values

E_POINTER
The pointer was not valid.
NOERROR
Success.


ISilenceSuppressor::SetEchoThreshold

[This is preliminary documentation and subject to change.]

Echo threshold is used in conjunction with running average sample buffer energy to determine which buffers are classified as silent. This method sets the echo threshold.

HRESULT SetEchoThreshold(
  DWORD dwEchoThreshold
);

Parameters

dwEchoThreshold
[in] Echo threshold.

Return Values

NOERROR
Success.


ISilenceSuppressor::GetUseAverageEnergyFunction

[This is preliminary documentation and subject to change.]

The average energy function is used to calculate average energy of sample buffers. This method returns a pointer to the current function.

HRESULT GetUseAverageEnergyFunction(
  BOOL *lpfUseAverageEnergyFunction
);

Parameters

lpfUseAverageEnergyFunction
[out] Pointer to average energy function.

Return Values

E_POINTER
The pointer was not valid.
NOERROR
Success.


ISilenceSuppressor::SetUseAverageEnergyFunction

[This is preliminary documentation and subject to change.]

The average energy function is used to calculate average energy of sample buffers. This method sets the function.

HRESULT SetUseAverageEnergyFunction(
  BOOL fUseAverageEnergyFunction
);

Parameters

fUseAverageEnergyFunction
[in] Average energy function.

Return Values

NOERROR
Success.


H26X Video Control Interfaces

[This is preliminary documentation and subject to change.]

There are two interfaces for the decoder and three interfaces for the encoder. The decoder interfaces are IH26XVideoEffects and IH26XSnapshot. The IH26XVideoEffects interface is used to set brightness, contrast, and saturation. The tint setting is not implemented. The IH26XSnapshot interface lets the programmer retrieve the current picture in YUV12 format. Any method may be called at any time. However, the Snapshot methods return an error if called when the decoder is not decoding frames.

The encoder interfaces are IH26XEncoderControl, IH26XRTPControl, and IH26XEncodeOptions (H263 only). The IH26XEncoderControl interface permits the setting of frame size and quality. The IH26XRTPControl interface allows you to program RTP parameters: packet size and packet loss. The IH26XEncodeOptions interface lets you set extended motion vectors, PB frames, and advanced prediction. For RTP, however, packet size and packet loss will update the codec at each frame only if bRTPHeader has been set to TRUE prior to StartStreaming. The E_FAIL or S_OK codes are the only ones returned.

H26X Video Control Interfaces | Description
IH26XVideoEffects | Sets brightness, contrast, and saturation.
IH26XEncodeOptions | Sets extended motion vectors, PB frames, and advanced prediction.
IH26XSnapshot | Retrieves the next decoded frame in YUV12 format.
IH26XEncoderControl | Sets frame size and quality.
IH26XRTPControl | Program RTP parameters, such as packet size and packet loss.


IH26XVideoEffects

[This is preliminary documentation and subject to change.]

The methods of this interface set brightness, contrast, and saturation. They may be called at any point and will take effect on the next frame processed.

Constants and Structures

H26X_VIDEO_EFFECT

VIDEO_EFFECT_VALUES

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IH26XVideoEffects Methods | Description
getFactoryDefault | Returns the factory default for the specified effect.
getFactoryLimits | Returns the factory limits for the specified effect.
getCurrent | Gets the current value for the specified effect.
setCurrent | Sets the current value for the specified effect.
resetCurrent | Resets the current value for the specified effect.


H26X_VIDEO_EFFECT

[This is preliminary documentation and subject to change.]

typedef enum
{
   H26X_VE_UNDEFINED,
   H26X_VE_BRIGHTNESS,
   H26X_VE_CONTRAST,
   H26X_VE_SATURATION,
   H26X_VE_TINT,
   H26X_VE_MIRROR,
   H26X_VE_ASPECT_CORRECT
} H26X_VIDEO_EFFECT;


VIDEO_EFFECT_VALUES

[This is preliminary documentation and subject to change.]

typedef struct
{
   int iBrightness;
   int iSaturation;
   int iContrast;
   int iMirror;
   int iAspectCorrect;
} VIDEO_EFFECT_VALUES, * PTR_VIDEO_EFFECT_VALUES;


IH26XVideoEffects::getFactoryDefault

[This is preliminary documentation and subject to change.]

Returns the factory default for the specified effect.

HRESULT getFactoryDefault(
  H26X_VIDEO_EFFECT veVideoEffect,
  int *pinDefault
);

Parameters

veVideoEffect
[in] Video effect.
pinDefault
[out] Factory default value for veVideoEffect.

Return Values

E_FAIL
Method failed.
S_OK
Method succeeded.


IH26XVideoEffects::getFactoryLimits

[This is preliminary documentation and subject to change.]

Returns the factory limits for the specified effect.

HRESULT getFactoryLimits(
  H26X_VIDEO_EFFECT veVideoEffect,
  int *pinLower,
  int *pinUpper
);

Parameters

veVideoEffect
[in] Effect for which limit information is needed.
pinLower
[out] Lower limit for value of effect.
pinUpper
[out] Upper limit for value of effect.

Return Values

E_FAIL
Method failed.
S_OK
Method succeeded.


IH26XVideoEffects::getCurrent

[This is preliminary documentation and subject to change.]

Gets the current value for the specified effect.

HRESULT getCurrent(
  H26X_VIDEO_EFFECT veVideoEffect,
  int *pinValue
);

Parameters

veVideoEffect
[in] Effect for which current value is needed.
pinValue
[out] Current value of effect.

Return Values

E_FAIL
Method failed.
S_OK
Method succeeded.


IH26XVideoEffects::setCurrent

[This is preliminary documentation and subject to change.]

Sets the current value for the specified effect.

HRESULT setCurrent(
  H26X_VIDEO_EFFECT veVideoEffect,
  int inValue
);

Parameters

veVideoEffect
[in] Effect set.
inValue
[in] Value to which effect is set.

Return Values

E_FAIL
Method failed.
S_OK
Method succeeded.


IH26XVideoEffects::resetCurrent

[This is preliminary documentation and subject to change.]

Resets the current value for the specified effect.

HRESULT resetCurrent(
  H26X_VIDEO_EFFECT veVideoEffect
);

Parameters

veVideoEffect
[in] TBD

Return Values

E_FAIL
Method failed.
S_OK
Method succeeded.


IH26XEncodeOptions

[This is preliminary documentation and subject to change.]

The methods in this interface sets extended motion vectors, PB frames, and advanced prediction. These may be called at any point and will take effect on the next frame.

Structures

ENCODE_OPTIONS_VALUES

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IH26XEncodeOptions Methods | Description
get_EncodeOptions | Gets encode parameters structure.
get_EncodeOptionsDefault | Sets encode parameters to default structure.
set_EncodeOptions | Sets encode parameters structure.


ENCODE_OPTIONS_VALUES

[This is preliminary documentation and subject to change.]

typedef struct
{
   int bExtendedMV;
   int bPBFrames;
   int bAdvPrediction;
} ENCODE_OPTIONS_VALUES, * PTR_ENCODE_OPTIONS_VALUES;


IH26XEncodeOptions::get_EncodeOptions

[This is preliminary documentation and subject to change.]

Gets encode parameters structure.

HRESULT get_EncodeOptions(
  PTR_ENCODE_OPTIONS_VALUES pOptionValues
);

Parameters

pOptionValues
[out] Pointer to structure containing encode options.

Return Values

E_FAIL
Method failed.
S_OK
Method succeeded.


IH26XEncodeOptions::get_EncodeOptionsDefault

[This is preliminary documentation and subject to change.]

Sets encode parameters to default structure.

HRESULT get_EncodeOptionsDefault(
  PTR_ENCODE_OPTIONS_VALUES pOptionValues
);

Parameters

pOptionValues
[out] Pointer to structure containing encode default options.

Return Values

E_FAIL
Method failed.
S_OK
Method succeeded.


IH26XEncodeOptions::set_EncodeOptions

[This is preliminary documentation and subject to change.]

Sets encode parameters structure.

HRESULT set_EncodeOptions(
  PTR_ENCODE_OPTIONS_VALUES pOptionValues
);

Parameters

pOptionValues
[in] Pointer to structure containing encode options.

Return Values

E_FAIL
Method failed.
S_OK
Method succeeded.


IH26XSnapshot

[This is preliminary documentation and subject to change.]

This interface retrieves the next decoded frame in YUV12 format. A timeout is provided so that the interface returns to the caller.

Structures

LPBITMAPINFOHEADER

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IH26XSnapshot Methods | Description
getBitmapInfoHeader | Gets a bitmap info header for the currently decoded picture.
getSnapshot | Gets the next picture that is decoded.


LPBITMAPINFOHEADER

[This is preliminary documentation and subject to change.]

typedef struct
{
   DWORD      biSize;
   LONG       biWidth;
   LONG       biHeight;
   WORD       biPlanes;
   WORD       biBitCount;
   DWORD      biCompression;
   DWORD      biSizeImage;
   LONG       biXPelsPerMeter;
   LONG       biYPelsPerMeter;
   DWORD      biClrUsed;
   DWORD      biClrImportant;
} *LPBITMAPINFOHEADER;


IH26XSnapshot::getBitmapInfoHeader

[This is preliminary documentation and subject to change.]

Gets a bitmap info header for the currently decoded picture.

HRESULT getBitmapInfoHeader(
  LPBITMAPINFOHEADER lpBmi
);

Parameters

lpBmi
[out] Pointer to map information header.

Return Values

E_FAIL
Method failed.
S_OK
Method succeeded.


IH26XSnapshot::getSnapshot

[This is preliminary documentation and subject to change.]

Gets the next picture that is decoded.

HRESULT getSnapshot(
  LPBITMAPINFOHEADER lpBmi,
  unsigned char *pvBuffer,
  DWORD dwTimeout
);

Parameters

lpBmi
[in] Pointer to map information header.
pvBuffer
[out] Pointer to buffer containing next picture.
dwTimeout
[in] Timeout for retrieving next picture.

Return Values

E_FAIL
Method failed.
S_OK
Method succeeded.


IH26XEncoderControl

[This is preliminary documentation and subject to change.]

The methods of this interface permit the setting of frame size and quality.

Structures

ENC_CMP_DATA

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IH26XEncoderControl Methods | Description
get_EncodeCompression | Gets encode parameters structure.
get_EncodeCompressionDefault | Sets encode parameters to default values.
set_EncodeCompression | Sets encode parameters.


ENC_CMP_DATA

[This is preliminary documentation and subject to change.]

typedef struct {
   DWORD dwTargetFrameSize;
   BOOL  bFrameSizeBRC;
   BOOL  bSendKey;
   DWORD dwQuality;
   DWORD dwFrameRate;
   DWORD dwDataRate;
   DWORD dwScale;
   DWORD dwWidth;
   DWORD dwKeyFrameInterval;
} ENC_CMP_DATA, * PTR_ENC_CMP_DATA;


IH26XEncoderControl::get_EncodeCompression

[This is preliminary documentation and subject to change.]

Gets encode parameters structure.

HRESULT get_EncodeCompression(
  PTR_ENC_CMP_DATA pData
);

Parameters

pData
[out] Pointer to ENC_CMP_DATA structure containing compression data.

Return Values

E_FAIL
Method failed.
S_OK
Method succeeded.


IH26XEncoderControl::get_EncodeCompressionDefault

[This is preliminary documentation and subject to change.]

Sets encode parameters to default values.

HRESULT get_EncodeCompressionDefault(
  PTR_ENC_CMP_DATA pData
);

Parameters

pData
[out] Pointer to ENC_CMP_DATA structure containing default compression data.

Return Values

E_FAIL
Method failed.
S_OK
Method succeeded.


IH26XEncoderControl::set_EncodeCompression

[This is preliminary documentation and subject to change.]

Sets encode parameters.

HRESULT set_EncodeCompression(
  PTR_ENC_CMP_DATA pData
);

Parameters

pData'
[in] Sets compression parameters to values contained in ENC_CMP_DATA structure.

Return Values

E_FAIL
Method failed.
S_OK
Method succeeded.


IH26XRTPControl

[This is preliminary documentation and subject to change.]

The element bRTPHeader must be set to TRUE prior to StartStreaming. If this element is TRUE then dwPacketSize and dwPacketLoss can be set at any time, and will take effect on the next frame. The state of bRTPHeader cannot be changed between StartStreaming and StopStreaming.

Structures

ENC_RTP_DATA

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IH26XRTPControl Methods | Description
get_RTPCompression | Gets the encode RTP parameters structure.
get_RTPCompressionDefault | Sets the encode RTP parameters to default values.
set_RTPCompression | Sets the encode RTP parameters


ENC_RTP_DATA

[This is preliminary documentation and subject to change.]

typedef struct {
   BOOL bRTPHeader;
   DWORD dwPacketSize;
   DWORD dwPacketLoss;
} ENC_RTP_DATA, * PTR_ENC_RTP_DATA;


IH26XRTPControl::get_RTPCompression

[This is preliminary documentation and subject to change.]

Gets the encode RTP parameters structure.

HRESULT get_RTPCompression(
  PTR_ENC_RTP_DATA pData
);

Parameters

pData
[out] Returns pointer to ENC_RTP_DATA structure containing RTP parameters.

Return Values

E_FAIL
Method failed.
S_OK
Method succeeded.


IH26XRTPControl::get_RTPCompressionDefault

[This is preliminary documentation and subject to change.]

Sets the encode RTP parameters to default values.

HRESULT get_RTPCompressionDefault(
  PTR_ENC_RTP_DATA pData
);

Parameters

pData
[out] Returns ENC_RTP_DATA structure containing RTP default parameters.

Return Values

E_FAIL
Method failed.
S_OK
Method succeeded.


IH26XRTPControl::set_RTPCompression

[This is preliminary documentation and subject to change.]

Sets the encode RTP parameters.

HRESULT set_RTPCompression(
  PTR_ENC_RTP_DATA pData
);

Parameters

pData
[in] Input ENC_RTP_DATA structure containing required RTP parameters.

Return Values

E_FAIL
Method failed.
S_OK
Method succeeded.


A

Analog Display Services Interface (ADSI)
A Bellcore standard defining a protocol on the flow of information between a switch, a server, a voice mail system, or service bureau, for example, and a subscriber's telephone, PC, data terminal, or other communicating device with a screen. ADSI enables a text version of the conversation to be displayed on the screen during the telephone connection. As an example, the user dials into a voice mail account and receives an audio menu for the voice mail functions while the screen displays the menu in text form.
Assisted Telephony
The set of functions that are not just dedicated to telephonic functionality, but are designed to make the establishment of voice calls and media calls available to any Win32-based application. See also Basic Telephony, Extended Telephony, Supplementary Telephony.
asynchronous
Data transmission method that allows characters to be sent at irregular intervals over a line by preceding each character with a start bit and following it with a stop bit. See also synchronous.


B

B channel
A bearer channel that is a fundamental component of ISDN interfaces. It carries 64,000 bits per second (bps) in both directions, is circuit-switched, and is able to carry either voice or data. See also D channel, Integrated Services Digital Network (ISDN).
band
The range of frequencies between two defined points.
bandwidth
In communications, the difference between the highest and lowest frequencies in a given range. For example, a telephone accommodates a bandwidth of 3000 Hz, the difference between the lowest (300 Hz) and highest (3300 Hz) frequencies it can carry.
Bandwidth Allocation Control Protocol (BACP)
The set of rules that manage bandwidth over dynamic multi-link PPP connections. See also multi-link PPP, point-to-point protocol (PPP).
Basic Rate Interface (BRI-ISDN)
The standard ISDN line, consisting of two B channels and one D channel. See also Integrated Services Digital Network (ISDN), Primary Rate Interface (PRI-ISDN).
Basic Telephony
An elementary level of telephony service, with a minimal subset of features, that provides a minimum set of functions that corresponds to Plain Old Telephone Service (POTS). TAPI service providers are required to support all Basic Telephony functions. See also Assisted Telephony, Extended Telephony, Supplementary Telephony.
BRI-ISDN
See Basic Rate Interface (BRI-ISDN).
bps
See bits per second (bps).
bits per second (bps)
Transfer-rate measurement indicating how many bits of computer data are sent in a one-second period through a modem over a telephone line.


C

call classification
TAPI process that reports changes in the type of media stream (voice, fax, data modem, and so on) to participating applications.
call progress monitoring
The process of listening for audible tones such as a dial tone, special information tones, busy signals, and ringback tones to determine the state of a call (its progress through the network).
call redirection
A function that allows an application to deflect an offering call to another address without first answering the call. Call redirection differs from call forwarding in that call forwarding is performed by the switch without the involvement of the application; redirection can be done on a call-by-call basis by the application, for example, driven by caller ID information. It differs from call transfer in that transferring a call requires that the call first be answered. See also called-ID, caller-ID, redirecting ID, redirection ID.
called-ID
A parameter of the call redirection function that identifies the party originally dialed by the caller. See also call redirection.
caller-ID
A parameter of the call redirection function that identifies the originating party of a call. See also call redirection.
central office
Telephone company's local facility that provides telephone service in a specific area.Typically, subscribers' lines are joined to switching equipment that connects other subscribers to each other, locally and over long distance. Also called CO.
Centrex
A business telephone service offered by a local telephone company from a local, central office.
computer-centric connection
A connection that uses a computer add-in card or external box that is connected to both the telephone network and the phone set. Compare phone-centric connection.
connected-ID
Identifier for the party to which the call was actually connected. This may be different from the called party if the call was diverted.


D

D channel
A data channel of the ISDN interface. It is one of the three standard channels on a Basic Rate ISDN line. On a BRI-ISDN line, a D channel can carry signaling information and low-speed packet data at a rate of 16,000 bps. On a PRI-ISDN line, the D channel runs at 64,000 bps.See also Basic Rate Interface (BRI-ISDN), B channel, Primary Rate Interface (PRI-ISDN).
device class
A group of related physical devices or device drivers through which applications send and receive the information or data that makes up a call.
DID
See direct inward dialing (DID).
direct inward dialing (DID)
An ability provided by virtually all modern PBXs that allows an external caller to reach an internal extension by dialing a standard seven-digit telephone number without having to pass through an operator or attendant. See also private branch exchange (PBX).
DLL
See dynamic-link library (DLL).
dynamic-link library (DLL)
A feature that allows executable code modules to be loaded on demand and linked at run time. This enables the library-code fields to be updated automatically, transparent to applications, and then unloaded when they are no longer needed.


E

Extended Telephony
Level of telephony service in which the API provides well-defined API extension mechanisms that enable application developers to access service provider-specific functions not directly defined by the Telephony API. See also Assisted Telephony, Basic Telephony, Supplementary Telephony.


I

Integrated Services Digital Network (ISDN)
A completely digital telephone/telecommunications network for carrying voice, data, images, and video at high speed by sending digitally encoded signals at speeds of up to 144,000 bps on Basic Rate Interface (BRI-ISDN) lines and much higher on Primary Rate Interface (PRI-ISDN) lines. ISDN is composed of at least three channels and as many as 32 channels, for simultaneous, independently operated transmission of voice and data. See also Basic Rate Interface (BRI-ISDN), Primary Rate Interface (PRI-ISDN).
inverse multiplexing
The process whereby bandwidth enables a call to transmit more information at the same time in the same timeframe than information from a single signal transmitted over a single channel. This is accomplished by splitting a single high-speed channel into multiple signals, transmitting the multiple signals over multiple facilities operating at a lower rate than the original signal, and then recombining the separately transmitted portions into the original signal at the original rate. See also bandwidth.
ISDN
See Integrated Services Digital Network (ISDN).


K

Kbps
See kilobits per second (Kbps).
kHz
See kilohertz (kHz).
kilobits per second (Kbps)
One thousand bits per second. Standard measure of data rate and transmission capacity.
kilohertz (kHz)
In data communications, kHz means a thousand bits per second. In computer memory terms, kHz means 1,024, which is the figure for two raised to the 10th power.


L

line device
A physical channel composed of a telephone line and the hardware to control it such as a fax board, a modem, or an ISDN card. The simplest kind of line device corresponds to exactly one telephone line.
line device class
A device-independent representation of a physical line device, such as a modem.
local loop
The part of the telephone network between the telephone and the telephone company's central switching office. Within this loop, human speech from a household telephone is usually transmitted in analog format, and the digital data from a computer must first be converted to analog by a modem. Digital networks are gradually replacing analog in the local loop.


M

MAPI
See Microsoft Messaging API (MAPI).
Mbps
See megabits per second (Mbps).
media mode
The form in which data is transmitted on a line.
media stream
The type of information exchanged over a call.
megabits per second (Mbps)
1,544,000 bits per second (bps). See also bits per second (bps).
megahertz (MHz)
One million cycles per second; a unit of frequency used to measure band and bandwidth. See also band, bandwidth.
MHz
See megahertz (MHz).
Microsoft Messaging API (MAPI)
Set of API functions and an OLE interface that lets messaging clients, such as Microsoft Exchange, interact with various message service providers and various computer telephony servers running Windows NT Server.
multi-link PPP
A communications protocol that allows the combination of two or more B channels into a single, faster PPP connection. With multi-link PPP, you can have a 128-Kbps PPP connection over a Basic Rate ISDN line. See also Basic Rate Interface (BRI-ISDN), point-to-point protocol (PPP).


P

phone-centric connection
A connection that consists of a single POTS line in which the computer is connected to the switch through the desktop phone set. Compare computer-centric connection.
Plain Old Telephone Service (POTS)
Basic telephony service supplying standard single-line telephones, telephone lines, and access to the public switched network.
point-to-point protocol (PPP)
A communications protocol that allows a computer to connect to other computers over a standard dial-up telephone line using a high-speed modem.
POTS
See Plain Old Telephone Service (POTS).
PRI-ISDN
See Primary Rate Interface (PRI-ISDN).
Primary Rate Interface (PRI-ISDN)
A type of ISDN service that offers 23 B channels at 64 Kbps and one D channel at 64 Kbps (23B+D). In Europe, PRI provides for 30 B channels and two D channels (30B+2D). See also Basic Rate Interface (BRI-ISDN).
private branch exchange (PBX)
A private telephone switching system, usually located on a customer's premises with an attendant console. The PBX is connected to a common group of lines from one or more central offices to provide service to a number of individual phones, such as in a hotel, business, or government office. PBXs often use proprietary digital-line protocols, although some are analog based.
provisioning
The combination of device and service options that make up an ISDN line. When you order your ISDN line, the telephone company provisions the line, that is, it configures your ISDN service according to the physical capabilities of the switch, as well as the options you choose.
public switched telephone network (PSTN)
The local analog telephone network, which provides 3.1 kHz voice-grade quality of service (its bearer mode).


R

redirecting-ID
Parameter of the call redirection function that identifies to the caller the original destination from which the call was diverted (redirected). See also call redirection.
redirection-ID
Parameter of the call redirection function that identifies to the caller the number to which the call is now diverted (redirected). See also call redirection.


S

service provider
A dynamic-link library that supports communications over a telephone network through a set of exported service functions. The service provider responds to telephony requests, sent to it by the TAPI dynamic-link library, by carrying out the low-level tasks necessary to communicate over the telephone network. In this way, the service provider, in conjunction with TAPI, shields applications from the service- and technology-dependent details of the telephone network communication.
subaddressing
A capability provided on ISDN lines that allows more information than just a single telephone number to be used when dialing.
Supplementary Telephony
Level of service that provides advanced switch features such as hold, transfer, and so on. All supplementary services are optional; that is, the service provider is not required to support them. See also Assisted Telephony, Basic Telephony, Extended Telephony.
Switched 56
A switched data service that lets the user dial someone else and transmit at full duplex, digital synchronous 56 Kbps for the price of a phone call.
synchronous
Data transmission method in which there is constant time between successive bits, characters, or events. The timing is achieved by the sharing of a single clock. Each end of the transmission synchronizes itself with the use of clocks and information sent along with the transmitted data. Characters are spaced by time, not by start and stop bits. See also asynchronous.


T

T1/E1
A digital tranmission link with a capacity of 1,544 Mbps. In the US, this link is called T1. In Europe, it is called E1. See also megabits per second (Mbps).
TAPI
See Telephony application programming interface (TAPI).
tapisrv.exe
A support-service application that provides an execution context for the TAPI dynamic-link library to carry out duties such as allocating memory or accessing data structures that have been swapped out to disk.
TDD
See Telecommunications Devices for the Deaf (TDD).
Telecommucations Devices for the Deaf (TDD)
A data device for the transmission of coded signals. Typically, the device is a simple computer terminal consisting of a keyboard, acoustic coupler, and display, and runs at 300 baud.
telephony
The science of transmitting voice, data, video, or image signals over a distance using technology that integrates computers with the telephone network.
Telephony application programming interface (TAPI)
Set of functions that allows programming of telephone line-based devices in a device-independent manner, giving personal telephony to users. TAPI supports both speech and data transmission, allows for a variety of terminal devices, and supports complex connection types and call-management techniques such as conference calls, call waiting, and voice mail. TAPI allows all elements of telephone usage—from the simple dial-and-speak call to international e-mail—to be controlled within applications developed for the Microsoft® Win32® application programming interface (API).
Telephony service provider interface (TSPI).
Tool for creating service providers for the Microsoft Windows family of operating systems that support the Microsoft Win32 application programming interface (API). Win32 TSPI defines how the network shares information with Windows Telephony, which in turn talks to the API, which talks to the Windows Telephony applications.
third-party call control
A party call-control model that allows an application to establish or answer a call between any two parties.
threads
Individual processes within a single application.
tick count
The number of milliseconds since Windows started.
timestamp
An imprint of time/date created when a specific event or process takes place.
TSPI
See Telephony service provider interface (TSPI).
twisted pair
Regular telephone wiring. Each telephone wire is actually a pair of wires.


U

UniModem
The universal modem driver in TAPI. UniModem is a driver-level component that uses modem description files to control its interaction with the communications driver, VCOMM. See also VCOMM.
user-user information
Information that is sent from one user to another by the remote station (ISDN).


V

VCOMM
A communications device driver within TAPI. VCOMM can assign protected mode to TAPI services and allows Windows applications and drivers to use ports and modems. See also UniModem.
voice signal
Considered to be any signal that can travel over a 3.1 kHz-bandwidth channel.


W

Windows Open Services Architecture (WOSA)
Software architecture that provides a single system-level interface for connecting front-end applications with back-end services. Windows Telephony is part of WOSA.


Symbols

2B+D
Designation for the way a Basic Rate ISDN line is configured, using two B channels and one D channel. See also B channel, Basic Rate Interface (BRI-ISDN), D channel.


IP Telephony with TAPI 3.0

[This is preliminary documentation and subject to change.]

Summary

TAPI 3.0 is an evolutionary API providing convergence of both traditional PSTN telephony and IP Telephony.

IP Telephony is an emerging set of technologies which enables voice, data, and video collaboration over existing LANs, WANs and the Internet.

TAPI 3.0 enables IP Telephony on the Microsoft® Windows® operating system platform by providing simple and generic methods for making connections between two or more machines, and accessing any media streams involved in the connection.

TAPI 3.0 supports standards based H.323 conferencing and IP multicast conferencing. It utilizes the Windows NT® 5.0 operating system's Active Directory service to simplify deployment within an organization, and includes quality of service (QoS) support to improve conference quality and network manageability.

Introduction to TAPI 3.0

Introduction to H.323 Communications in TAPI 3.0

IP Multicast Conferencing in TAPI 3.0

Quality of Service

Enterprise Deployment of TAPI 3.0 IP Telephony Infrastructure

TAPI 3.0 and NetMeeting 2.0


Introduction to IP Telephony

[This is preliminary documentation and subject to change.]

What is IP Telephony?

IP Telephony is an emerging set of technologies that enables voice, data, and video collaboration over existing IP-based LANs, WANs, and the Internet.

Specifically, IP Telephony uses open IETF and ITU standards to move multimedia traffic over any network that uses IP (the Internet Protocol)—offering users both flexibility in physical media (for example, POTS lines, ADSL, ISDN, leased lines, coaxial cable, satellite, and twisted pair) and flexibility of physical location. As a result, the same ubiquitous networks that carry Web, e-mail and data traffic can be used to connect to individuals, businesses, schools and governments worldwide.

TAPI 3.0 is an evolutionary API that supports convergence of both traditional PSTN telephony and telephony over IP networks.

What are the Benefits of IP Telephony?

IP Telephony allows organizations and individuals to lower the costs of existing services, such as voice and broadcast video, while at the same time broadening their means of communication to include modern video conferencing, application sharing, and whiteboarding tools.

In the past, organizations have deployed separate networks to handle traditional voice, data, and video traffic. Each with different transport requirements, these networks were expensive to install, maintain, and reconfigure. Furthermore, since these networks were physically distinct, integration was difficult if not impossible, limiting their potential usefulness.

IP Telephony blends voice, video and data by specifying a common transport, IP, for each, effectively collapsing three networks into one. The result is increased manageability, lower support costs, a new breed of collaboration tools, and increased productivity.

Possible applications for IP Telephony include telecommuting, real-time document collaboration, distance learning, employee training, video conferencing, video mail, and video on demand.


Introduction to TAPI 3.0

[This is preliminary documentation and subject to change.]

What is TAPI 3.0?

As telephony and call control become more common in the desktop computer, a general telephony interface is needed to enable applications to access all the telephony options available on any machine. Additionally, it is imperative that the media or data on a call is available to applications in a standard manner.

TAPI 3.0 is an architecture that provides simple and generic methods for making connections between two or more machines, and accessing any media streams involved in that connection. It abstracts call-control functionality to allow different, and seemingly incompatible, communication protocols to expose a common interface to applications.

IP Telephony is a demand poised for explosive growth, as organizations begin an historic shift from expensive and inflexible circuit-switched public telephone networks to intelligent, flexible and inexpensive IP networks. Microsoft, in anticipation of this trend, has created a robust computer telephony infrastructure, TAPI. Now in its third major version, TAPI is suitable for quick and easy development of IP Telephony applications.

Inside TAPI 3.0

TAPI 3.0 integrates multimedia stream control with legacy telephony. Additionally, it is an evolution of the TAPI 2.1 API to the COM model, allowing TAPI applications to be written in any language, such as Java™, C/C++ and the Microsoft® Visual Basic® programming system.

Besides supporting classic telephony providers, TAPI 3.0 supports standard H.323 conferencing and IP multicast conferencing. TAPI 3.0 utilizes the Windows® NT 5.0 Active Directory service to simplify deployment within an organization, and it supports quality of service (QoS) features to improve conference quality and network manageability.

There are four major components to TAPI 3.0:

  • TAPI 3.0 COM API
  • TAPI Server
  • Telephony Service Providers
  • Media Stream Providers.

In contrast to TAPI 2.1, the TAPI 3.0 API is implemented as a suite of Component Object Model (COM) objects. Moving TAPI to the object-oriented COM model allows component upgrades of TAPI features. It also allows developers to write TAPI-enabled applications in any language, such as Java, Visual Basic, or C/C++.

The TAPI Server process (TAPISRV.EXE) abstracts the TSPI (TAPI Service Provider Interface) from TAPI 3.0 and TAPI 2.1, allowing TAPI 2.1 Telephony Service Providers to be used with TAPI 3.0, maintaining the internal state of TAPI.

Telephony Service Providers (TSPs) are responsible for resolving the protocol-independent call model of TAPI into protocol-specific call control mechanisms. TAPI 3.0 provides backward compatibility with TAPI 2.1 TSPs. Two IP Telephony service providers (and their associated MSPs) ship by default with TAPI 3.0: the H.323 TSP and the IP Multicast Conferencing TSP, which are discussed later in this document.

TAPI 3.0 provides a uniform way to access the media streams in a call, supporting the DirectShowTM API as the primary media stream handler. TAPI Media Stream Providers (MSPs) implement DirectShow interfaces for a particular TSP and are required for any telephony service that makes use of DirectShow streaming. Generic streams are handled by the application.

Call Control Model

There are five objects in the TAPI 3.0 API:

  • TAPI
  • Address
  • Terminal
  • Call
  • CallHub.

The TAPI object is the application's entry point to TAPI 3.0. This object represents all telephony resources to which the local computer has access, allowing an application to enumerate all local and remote addresses.

An Address object represents the origination or destination point for a call. Address capabilities, such as media and terminal support, can be retrieved from this object. An application can wait for a call on an Address object, or can create an outgoing call object from an Address object.

A Terminal object represents the sink, or renderer, at the termination or origination point of a connection. The Terminal object can map to hardware used for human interaction, such as a telephone or microphone, but can also be a file or any other device capable of receiving input or creating output.

The Call object represents an address's connection between the local address and one or more other addresses (This connection can be made directly or through a CallHub). The Call object can be imagined as a first-party view of a telephone call. All call control is done through the Call object. There is a call object for each member of a CallHub.

The CallHub object represents a set of related calls. A CallHub object cannot be created directly by an application - they are created indirectly when incoming calls are received through TAPI 3.0. Using a CallHub object, a user can enumerate the other participants in a call or conference, and possibly (because of the location independent nature of COM) perform call control on the remote Call objects associated with those users, subject to sufficient permissions:

To Place a Call

  • Create and initialize a TAPI object.
  • Use the TAPI object to all available Address objects on a machine (e.g. network cards, modems, ISDN lines, etc.).
  • Enumerate the supported address types of each Address object (e.g. a phone number, IP address, etc.).
  • Choose an Address object based on queries for support for appropriate media (audio, video, and so on) and address types.
  • Use the CreateCall() method of the Address object to create a Call object associated with a particular address.
  • Select appropriate Terminals on the Call object.
  • Call the Connect() method of Call object to place the call.

To Answer a Call

  • Create and initialize a TAPI object.
  • Use the TAPI object to all available Address objects on a machine (e.g. network cards, modems, ISDN lines, etc.).
  • Enumerate the supported address types of each Address object (e.g. a phone number, IP address, etc.).
  • Choose an Address object based on Address queries for support of appropriate media (audio, video, etc.) and address types.
  • Register an interest in specific media types with appropriate Address object.
  • Register a call event handler (i.e. implement an ITCallNotification interface) with the Address object.
  • TAPI notifies application of a new call through ITCallNotification and creates a Call object.
  • Select appropriate Terminals on the Call object.
  • Call the Connect() method of Call object to place the call.
  • Call the Answer() method of Call object to answer the call.

Media Streaming Model

The Windows® operating system provides an extensible framework for efficient control and manipulation of streaming media called the DirectShow API. DirectShow, through its exposed COM interfaces, provides TAPI 3.0 with unified stream control.

At the heart of the DirectShow services is a modular system of pluggable components called filters, arranged in a configuration called a filter graph. A component called the filter graph manager oversees the connection of these filters and controls the stream's data flow. Each filter's capabilities are described by a number of special COM interfaces called pins. Each pin instance can consume or produce streaming data, such as digital audio.

While COM objects are usually exposed in user mode programs, the DirectShow streaming architecture includes an extension to the Windows driver model that allows the connection of media streams directly at the device driver level. The diagram below shows a simple PSTN-to-IP bridge: A 64 Kbps voice stream from an ISDN line is compressed into a G.723 audio stream and passed to an RTP payload handler, to be sent out over the network.

These high-performance streaming extensions to the Windows driver model avoid user-to-kernel mode transitions, and allow efficient routing of data streams between different hardware components at the device driver level. Each kernel mode filter is mirrored by a corresponding user mode proxy that facilitates connection setup and can be used to control hardware-specific features.

DirectShow network filters extend the streaming architecture to machines connected on an IP network. The Real-Time Transport protocol (RTP), designed to carry real-time data over connectionless networks, transports TAPI media streams and provides appropriate time stamp information. TAPI 3.0 includes a kernel mode RTP network filter.

TAPI 3.0 utilizes this technology to present a unified access method for the media streams in multimedia calls. Applications can route these streams by manipulating corresponding filter graphs; they can also easily connect streams from multiple calls for bridging and conferencing capabilities.


Introduction to H.323 Communications in TAPI 3.0

[This is preliminary documentation and subject to change.]

What is H.323?

H.323 is a comprehensive International Telecommunications Union (ITU) standard for multimedia communications (voice, video, and data) over connectionless networks that do not provide a guaranteed quality of service, such as IP-based networks and the Internet. It provides for call control, multimedia management, and bandwidth management for point-to-point and multipoint conferences. H.323 mandates support for standard audio and video codecs and supports data sharing via the T.120 standard. Furthermore, the H.323 standard is network, platform, and application independent, allowing any H.323 compliant terminal to interoperate with any other.

H.323 allows multimedia streaming over current packet-switched networks. To counter the effects of LAN latency, H.323 uses as a transport the Real-time Transport Protocol (RTP), an IETF standard designed to handle the requirements of streaming real-time audio and video over the Internet.

The H.323 standard specifies three command and control protocols:

  • H.245 for call control
  • Q.931 for call signaling
  • The RAS (Registration, Admissions, and Status) signaling function

The H.245 control channel is responsible for control messages governing operation of the H.323 terminal, including capability exchanges, commands, and indications. Q.931 is used to setup a connection between two terminals, while RAS governs registration, admission, and bandwidth functions between endpoints and gatekeepers (RAS is not used if a gatekeeper is not present). See below for more information on gatekeepers.

H.323 defines four major components for an H.323 based communications system:

  • Terminals
  • Gateways
  • Gatekeepers
  • Multipoint control units (MCUs).

Terminals are the client endpoints on the network. All terminals must support voice communications; video and data support is optional.

A Gateway is an optional element in an H.323 conference. Gateways bridge H.323 conferences to other networks, communications protocols, and multimedia formats. Gateways are not required if connections to other networks or non-H.323 compliant terminals are not needed.

Gatekeepers perform two important functions which help maintain the robustness of the network - address translation and bandwidth management. Gatekeepers map LAN aliases to IP addresses and provide address lookups when needed. Gatekeepers also exercise call control functions to limit the number of H.323 connections, and the total bandwidth used by these connections, in an H.323 "zone". A Gatekeeper is not required in an H.323 system – however, if a Gatekeeper is present, terminals must make use of its services.

Multipoint Control Units (MCU) support conferences between three or more endpoints. An MCU consists of a required Multipoint Controller (MC) and zero or more Multipoint Processors (MPs). The MC performs H.245 negotiations between all terminals to determine common audio and video processing capabilities, while the Multipoint Processor (MP) routes audio, video, and data streams between terminal endpoints.

Any H.323 client is guaranteed to support the following standards: H.261 and G.711. H.261 is an ITU-standard video codec designed to transmit compressed video at a rate of 64 Kbps and at a resolution of 176x44 pixels (QCIF). G.711 is an ITU-standard audio codec designed to transmit A-law and µ-law PCM audio at bit rates of 48, 56, and 64 Kbps.

Optionally, an H.323 client may support additional codecs: H.263 and G.723. H.263 is an ITU-standard video codec based on and compatible with H.261. It offers improved compression over H.261 and transmits video at a resolution of 176 x 44 pixels (QCIF). G.723 is an ITU-standard audio codec designed to operate at very low bit rates.

The TAPI 3.0 H.323 Telephony Service Provider

The H.323 Telephony Service Provider (along with its associated Media Stream Provider) allows TAPI-enabled applications to engage in multimedia sessions with any H.323-compliant terminal on the local area network.

Specifically, the H.323 Telephony Service Provider (TSP) implements the H.323 signaling stack. The TSP accepts a number of different address formats, including name, machine name, and email address.

The H.323 MSP is responsible for constructing the DirectShow filter graph for an H.323 connection (including the RTP, RTP payload handler, codec, sink, and renderer filters).

H.323 Integration with NT 5.0 Active Directory

H.323 telephony is complicated by the reality that a user's network address (in this case, a user's IP address) is highly volatile and cannot be counted on to remain unchanged between H.323 sessions. The TAPI H.323 TSP utilizes the services of the Windows NT Active Directory to perform user-to-IP address resolution. Specifically, user-to-IP mapping information is stored and continually refreshed using the Internet Locator Service (ILS) Dynamic Directory, a real-time server component of the Active Directory.

The following user scenario illustrates IP address resolution in the H.323 TSP:

1. John wishes to initiate an H.323 conference with Alice, another user on the LAN. Once Alice's video conferencing application creates an Address object and puts it in listen mode, Alice's IP address is added to the Windows NT Active Directory by the H.323 TSP. This information has a finite time to live (TTL) and is refreshed at regular intervals via the Lightweight Directory Access Protocol (LDAP):

2. John's H.323 TSP then queries the ILS Dynamic Directory server for Alice's IP address. Specifically, John queries for any and all RTPerson objects in the Directory associated with Alice:

3. Armed with Alice's up-to-date IP address, John initiates an H.323 call to Alice's machine, and H.323-standard negotiations and media selection occurs between the peer TSPs on both machines. Once capability negotiations have been completed, both H.323 Media Stream Providers (MSPs) construct appropriate DirectShow filter graphs, and all media streams are passed off to DirectShow to handle. The conference then begins.


IP Multicast Conferencing in TAPI 3.0

[This is preliminary documentation and subject to change.]

What is IP Multicast Conferencing?

IP Multicast is an extension to IP that allows for efficient group communication. IP Multicast arose out of the need for a lightweight, scalable conferencing solution that solved the problems associated with real-time traffic over a datagram, "best-effort" network. There are many advantages to using IP Multicast: scalability, fault tolerance, robustness, and ease of setup.

The IP Multicast conferencing model incorporates the following key features:

  • No global coordination is needed to add and remove members from a conference.
  • To reach a multicast group, a user sends data to a single multicast IP address. No knowledge of the other users in a group is necessary.
  • To receive data, users register their interest in a particular multicast IP address with a multicast aware router. No knowledge of the other users in a group is necessary.
  • Routers hide the multicast implementation details from the user.

Traditional connection-oriented conferencing suffers from a number of problems:

User complexity: Users must know the location of every user they wish to converse with, limiting scalability and fault-tolerance and rendering it difficult for users to add and remove themselves from a conference.

Wasted bandwidth: A user wishing to broadcast data to N users must send data through N connections, as shown in the following diagram:

The total bandwidth required for multiparty conferences in which all users are sending data goes up as N2 the number of parties involved, leading to huge scalability problems. IP Multicast takes advantage of the actual network topology to eliminate the transmission of redundant data down the same communications links.

IP Multicast implements a lightweight, session-based communications model, which places relatively little burden on conference users. Using IP Multicast, users send only one copy of their information to a group IP address that reaches all recipients. IP Multicast is designed to scale well as the number of participants expands—adding one more user does not add a corresponding amount of bandwidth. Multicasting also results in a greatly reduced load on the sending server.

IP Multicast routes these one-to-many data streams efficiently by constructing a spanning tree, in which there is only one path from one router to any other. Copies of the stream are made only when paths diverge:

Without multicasting, the same information must either be carried over the network multiple times, one time for each recipient, or broadcast to everyone on the network, consuming unnecessary bandwidth and processing.

IP Multicast uses Class D Internet Protocol addresses to specify multicast host groups, ranging from 224.0.0.0 to 239.255.255.255. Both permanent and temporary group addresses are supported. Permanent addresses are assigned by the Internet Assigned Numbers Authority (IANA) and include 224.0.0.1, the "all-hosts group" used to address all multicast hosts on the local network, and 224.0.0.2, which addresses all routers on a LAN. The range of addresses between 224.0.0.0 and 224.0.0.255 is reserved for routing and other low-level network protocols. Other addresses and ranges have been reserved for applications, such as 224.0.13.000 to 224.0.13.255 for Net News (for more information, see RFC 1700, "Assigned Numbers" at ftp://ftp.internic.net/rfc/rfc1700.txt).

The transport protocol for IP Multicast is RTP (Real-time Transport Protocol), which provides a standard multimedia header giving timestamp, sequence numbering, and payload format information.

Applications for IP Multicast include video and audio conferencing, telecommuting, database and Web-site replication, distance learning, dissemination of stock quotes, and collaborative computing. At present, the largest demonstration of the capabilities of IP Multicast is the Internet MBONE (Multicast Backbone).

The MBONE is an experimental, global multicast network layered on top of the physical Internet. It has been in existence for about five years, and presently carries IETF meetings, NASA space shuttle launches, music, concerts, and many other live meetings and performances (for more information, see http://www.mbone.com).

The TAPI 3.0 IP Multicast Conferencing TSP

The IP Multicast Conferencing TSP is chiefly responsible for resolving conference names to IP multicast addresses, using the Session Description Protocol (SDP) conference descriptors stored in the ILS Dynamic Directory Conference Server. It is complemented by the Rendezvous conference controls, described later in this document.

The IP Multicast Conferencing MSP is responsible for constructing an appropriate DirectShow filter graph for an IP multicast connection (including RTP, RTP payload handler, codec, sink, and renderer filters).

Architectural Diagram:

IP Multicast Integration with NT 5.0 Active Directory

TAPI 3.0 uses the IETF standard Session Description Protocol to advertise IP multicast conferences across the enterprise. SDP descriptors are stored in the Windows NT Active Directory – specifically, in the ILS Dynamic Directory Conference Server. SDP is discussed in more detail later in this document. In contrast to the Dynamic Directory servers utilized by the H.323 TSP, there is only one ILS Conference Server per enterprise, since conference announcements are not continually refreshed, therefore consuming little bandwidth.

TAPI 3.0's IP multicast conference mechanism is illustrated in the following scenario, in which John wishes to initiate a multicast conference:

1. John's TAPI 3.0-enabled application utilizes the Rendezvous Controls (discussed in more detail later in this document) to create an SDP session descriptor on the ILS Conference Server. The SDP descriptor contains, among other things, the conference name, start and end time information, the IP multicast address of the conference, and the media types used for the conference.

2. Jim queries the ILS Conference Server for SDP descriptors of conferences matching his criteria:

3. Mary and Alice perform similar queries and use the SDP information they receive to decide to participate in John's conference. Armed with the multicast IP address of the conference, they join the multicast host group:

The TAPI 3.0 Rendezvous Controls

The Rendezvous Controls are a set of COM components that abstract the concept of a conference directory, providing a mechanism to advertise new multicast conferences and to discover existing ones. They provide a common schema (SDP) for conference announcement, as well as scriptable interfaces, authentication, encryption, and access control features.

The user may add, delete, and enumerate multicast conferences stored on an ILS Conference Server via the Rendezvous Controls. These controls manipulate conference data via the Lightweight Directory Access Protocol (LDAP).

Joining a conference is illustrated in the diagram above. The conferencing application uses the Rendezvous Controls to obtain session descriptors for the conferences that match the user's criteria (1,2). Access control lists (ACLs) protect each of the stored conference announcements, and whether or not an announcement is visible and accessible depends upon the user's credentials.

Once the user has chosen a conference (3), the user application searches for all Address objects that support the address type "Multicast Conference Name." The application then uses the conference name from the SDP descriptor as a parameter to the CreateCall() method of the appropriate Address object (4), passes the appropriate Terminal objects to the returned Call object, and calls Call->Connect().

The Rendezvous Controls store the conference information on an ILS Conference Server in a format defined by the Session Description Protocol (SDP), an IETF standard for announcing multimedia conferences. The purpose of SDP is to publicize sufficient information about a conference (time, media, and location information) to allow prospective users to participate if they so choose. Originally designed to operate over the Internet MBONE (IP Multicast Backbone), SDP has been integrated by TAPI 3.0 with the Windows NT Active Directory, thereby extending its functionality to local area networks.

An SDP descriptor advertises the following information about a conference:

A session description is broken into three main parts: a single Session Description, zero or more Time Descriptions, and zero or more Media Descriptions. The Session Description contains global attributes that apply to the whole conference or all media streams. Time Descriptions contain conference start, stop, and repeat time information, while Media Descriptions contain details that are specific to a particular media stream.

While traditional IP multicast conferences operating over the MBONE have advertised conferences using a push model based on the Session Announcement Protocol (SAP), TAPI 3.0 utilizes a pull-based approach using Windows NT Active Directory services. This approach offers numerous advantages, among them bandwidth conservation and ease of administration. See the "Integration with Windows NT 5.0 Active Directory" subsection for details.

Conference Security Model

TAPI 3.0's conference security system addresses the following needs:

  • Controlling who can create, delete, and view conference announcements.
  • Preventing conference eavesdropping.

TAPI 3.0 utilizes the security features of the Windows NT Active Directory and LDAP to provide for secure conferencing over insecure networks such as the Internet. Each object in the Active Directory can be associated with an Access Control List (ACL) specifying object access rights on a user or group basis. By associating ACLs with SDP conference descriptors, conference creators can specify who can enumerate and view conference announcements. User authentication is provided by the Windows NT security subsystem.

Session Descriptors are transmitted from the ILS Conference Server to the user over LDAP in encrypted form, via a Secure Sockets Layer (SSL) connection, ensuring that the SDP is safe from eavesdroppers:

IP Multicast makes no provision for authenticating users - any user may anonymously join a multicast host group. To keep conferences private, TAPI 3.0 allows an IP multicast conference to be encrypted, with the encryption key distributed from within the conference descriptor. Only users with sufficient permissions have access to a conference's SDP descriptor, and therefore the Multicast Encryption Key. Once an authenticated user fetches the encryption key, he or she can participate in the conference.


Quality of Service

[This is preliminary documentation and subject to change.]

What is Quality of Service?

In contrast to traditional data traffic, multimedia streams, such as those used in IP Telephony or videoconferencing, may be extremely bandwidth and delay sensitive, imposing unique quality of service (QoS) demands on the underlying networks that carry them. Unfortunately, IP, with a connectionless, "best-effort" delivery model, does not guarantee delivery of packets in order, in a timely manner, or at all. In order to deploy real-time applications over IP networks with an acceptable level of quality, certain bandwidth, latency, and jitter requirements must be guaranteed, and must be met in a fashion that allows multimedia traffic to coexist with traditional data traffic on the same network.

Bandwidth: Multimedia data, and in particular video, may require orders of more bandwidth than traditional networks have been provisioned to handle. An uncompressed NTSC video stream, for example, can require upwards of 220 megabits per second to transmit. Even compressed, a handful of multimedia streams can completely overwhelm any other traffic on the network.

Latency: The amount of time a multimedia packet takes to get from the source to the destination (latency) has a major impact on the perceived quality of the call. There are many contributors towards latency, including transmission delays, queuing delays in network equipment, and delays in host protocol stacks. Latency must be minimized in order to maintain a certain level of interactivity and to avoid unnatural pauses in conversation.

Jitter: In contrast to data traffic, real-time multimedia packets must arrive in order and on time to be of any use to the receiver. Variations in packet arrival time (jitter) must be below a certain threshold to avoid dropped packets (and therefore irritating shrieks and gaps in the call). Jitter, by determining receive buffer sizes, also affects latency.

Coexistence: In comparison with multimedia traffic, data traffic is relatively bursty, and arrives in unpredictable chunks (for instance, when someone opens a Web page, or downloads a file from an FTP site). Aggregations of such bursts can clog routers and cause gaps in multimedia conferences, leaving calls at the mercy of everyone on the network (including other IP Telephony users). Multimedia bandwidth must be protected from data traffic, and vice versa.

Public-switched telephone networks guarantee a minimum quality of service by allocating static circuits for every telephone call. Such an approach is simple to implement, but wastes bandwidth, lacks robustness, and makes voice, video, and data integration difficult. Furthermore, circuit-switched data paths are impossible to create using a connectionless network such as IP.

QoS support on IP networks offers the following benefits:

  • Support for real-time multimedia applications.
  • Assurance of timely transfers of large amounts of data.
  • The ability to share the network in a manner that avoids starving applications of bandwidth.

Quality of Service and TAPI 3.0

Quality of service in TAPI 3.0 is handled through the DirectShow RTP filter, which negotiates bandwidth capabilities with the network based on the requirements of the DirectShow codecs associated with a particular media stream. These requirements are indicated to the RTP filter by the codecs via its own QoS interface. The RTP filter then uses the COM Winsock2 GQoS interfaces to indicate, in an abstract form, its QoS requirements to the Winsock2 QoS service provider (QoS SP). The QoS SP, in turn, invokes a number of varying QoS mechanisms appropriate for the application, the underlying media, and the network, in order to guarantee appropriate end-to-end QoS. These mechanisms include:

  • The Resource Reservation Protocol (RSVP)
  • Local Traffic Control:
  • -Packet Scheduling
  • -802.1p
  • -Appropriate layer 2 signaling mechanisms
  • IP Type of Service and DTR header settings

RSVP

The Resource Reservation Protocol (RSVP) is an IETF standard designed to support resource (for example, bandwidth) reservations through networks of varying topologies and media. Through RSVP, a user's quality of service requests are propagated to all routers along the data path, allowing the network to reconfigure itself (at all network levels) to meet the desired level of service.

The RSVP protocol engages network resources by establishing flows throughout the network. A flow is a network path associated with one or more senders, one or more receivers, and a certain quality of service.A sending host wishing to send data that requires a certain QoS will broadcast, via an RSVP-enabled Winsock Service Provider, "path" messages toward the intended recipients. These path messages, which describe the bandwidth requirements and relevant parameters of the data to be sent, are propagated to all intermediate routers along the path.

A receiving host, interested in this particular data, will confirm the flow (and the network path) by sending "reserve" messages through the network, describing the bandwidth characteristics of data it wishes to receive from the sender. As these reserve messages propagate back toward the sender, intermediate routers, based on bandwidth capacity, decide whether or not to accept the proposed reservation and commit resources. If an affirmative decision is made, the resources are committed and reserve messages are propagated to the next hop on the path from source to destination.

Local Traffic Control

Packet Scheduling: This mechanism can be used in conjunction with RSVP (if the underlying network is RSVP-enabled) or without RSVP. Traffic is identified as belonging to one flow or another, and packets from each flow are scheduled in accordance with the traffic control parameters for the flow. These parameters generally include a scheduled rate (token bucket parameter) and some indication of priority. The former is used to pace the transmission of packets to the network. The latter is used to determine the order in which packets should be submitted to the network when congestion occurs.

801.2p: Traffic control can also be used to determine the 802.1 User Priority value (a MAC header field used to indicate relative packet priority) to be associated with each transmitted packet. 802.1p-enabled switches can then give preferential treatment to certain packets over others, providing additional quality of service support at the data link layer level.

Layer 2 Signaling Mechanisms: In response to Winsock 2 QoS APIs, the QoS service provider may invoke additional traffic control mechanisms depending on the specific underlying data link layer. It may signal an underlying ATM network, for instance, to setup an appropriate virtual circuit for each flow. When the underlying media is a traditional 802 shared media network, the QoS service provider may extend the standard RSVP mechanism to signal a Subnet Bandwidth Manager (SBM). The SBM provides centralized bandwidth management on shared networks.

IP Type of Service

Each IP packet contains a three-bit Precedence field, which indicates the priority of the packet. An additional field can be used to indicate a delay, throughput, or reliability preference to the network. Local traffic control can be used to set these bits in the IP headers of packets on particular flows. As a result, packets belonging to a flow will be treated appropriately later by three devices on the network. These fields are analogous to 802.1p priority settings but are interpreted by higher layer network devices.


Enterprise Deployment of TAPI 3.0 IP Telephony Infrastructure

[This is preliminary documentation and subject to change.]

TAPI 3.0 has been designed to scale from the smallest business up to the largest organizations, while at the same time taking advantage of the Windows NT Active Directory to bring IP Telephony to the enterprise.

Enterprise Layout for TAPI 3.0 IP Telephony

The diagram below illustrates the enterprise layout for a sample enterprise with two sites connected through the Internet. The ILS Dynamic Directory Servers and the ILS Dynamic Directory Conference Server, as explained above, provide functionality for point-to-point and multiparty conferencing. IP Telephony clients can utilize video and audio capture equipment, but can also support legacy telephones through the use of a PSTN add-in card.

The IP/PSTN Gateway digitizes incoming analog voice calls from PSTN lines and encapsulates them in H.323 streams, and vice versa, providing users with the ability to send and receive legacy voice calls through existing telephony infrastructure.

The H.323 Proxy allows H.323 clients connectivity with the Internet by forwarding H.323 streams through the enterprise firewall. This enables H.323 Internet, Intranet, and business-to-business connectivity.

The function of the IP Multicast Proxy is somewhat similar to that of the H.323 Proxy - to forward multicast conference packets - but also furnishes clients with the ability to propagate selected conference announcements to and from the Internet.

The IP Multicast Proxy monitors conference announcements stored on the ILS Dynamic Directory Conference Server and broadcasts conferences with appropriate scope and security attributes to the Internet using the Session Announcement Protocol (SAP).

Conversely, the IP Multicast Proxy listens for appropriate conferences from those broadcast over the Internet and populates the ILS Dynamic Directory Conference Server with these announcements. In this manner, the IP Multicast Proxy allows users conference connectivity over the Internet while ensuring the confidentiality and security of private conferences.

Windows NT 5.0 Active Directory Layout for IP Telephony

As discussed earlier, the H.323 TSP uses the services of the ILS Dynamic Directory component of the Active Directory to remove the burden of name to IP translation from the user.

At the network level, the Windows NT Active Directory model treats an organization as a collection of sites. Sites are regions of good connectivity, such as subnets or LANs, and typically correlate with physical locales such as campuses.

For bandwidth and performance reasons, ILS servers are typically distributed across the enterprise, one per site, with each ILS server (or a replicating cluster of severs) being responsible for maintaining user-to-IP mappings for their site. To conserve bandwidth, these volatile mappings are not replicated across sites.

TAPI 3.0 utilizes the Active Directory to associate users with particular ILS servers. Users wishing to place an IP telephone call first consult the Global Catalog (a replicated subset of the Active Directory) for the User object of the person they wish to call. The Telephony container in the User object contains the name of the ILS server for that user's site, which is then queried for the IP address in question.

The following scenario illustrates enterprise deployment of the TAPI 3.0 directory infrastructure. In this example, Alice wishes to initiate an H.323 call to John:

John's must previously register his ILS server name with the Active Directory Global Catalog. Upon initialization, John's H.323 TSP queried the Global Catalog for the Subnet object associated with his machine, and from that has derived what site John's subnet and machine belong to. The TSP then fetches the name of the ILS server (or cluster of replicating servers) from DNS records, and stores this information in John's User object.

Subsequently, Alice's H.323 TSP queries her local copy of the Global Catalog for the name of John's ILS server:

Alice's H.323 TSP then queries John's ILS server across the WAN for John's current IP address:

Alice then initiates an H.323 session with John:

The call abstraction inherent in TAPI allows this ILS and Active Directory interaction to occur transparently both to the user, and to the TAPI 3.0-enabled application.


TAPI 3.0 and NetMeeting 2.0

What is Microsoft NetMeeting 2.0?

Microsoft NetMeeting is a conferencing and collaboration tool designed for the Internet or intranet. NetMeeting also provides a set of programming interfaces for adding conferencing functionality to your applications. It helps small and large organizations take full advantage of the global reach of the Internet or corporate intranet for real-time communications and collaboration by combining IP Telephony and Conferencing functionality. Connecting to other NetMeeting users is made easy with the Microsoft Internet Locator Server (ILS), enabling participants to call each other from a dynamic directory within NetMeeting or from a World Wide Web page. While connected on the Internet or corporate intranet, participants can communicate with both voice and video, work together on virtually any Windows-based application, exchange or mark up graphics on an electronic whiteboard, transfer files, or use the text-based chat program. For more information on Microsoft NetMeeting 2.0, see http://www.microsoft.com/netmeeting.

Microsoft NetMeeting 2.0 Features

H.323 standards-based voice and video conferencing. Real-time, point-to-point audio conferencing over the Internet or corporate intranet enables a user to make voice calls to associates and organizations around the world. NetMeeting voice conferencing offers many features, including half-duplex and full-duplex audio support for real-time conversations, automatic microphone sensitivity level setting to ensure that meeting participants hear each other clearly, and microphone muting, which lets users control the audio signal sent during a call. This voice conferencing supports network TCP/IP connections.

Support for the H.323 protocol enables interoperability between NetMeeting 2.0 and other H.323-compatible voice clients. The H.323 protocol supports the ITU G.711 and G.723 audio standards and Internet Engineering Task Force (IETF) RTP and RTCP specifications for controlling audio flow to improve voice quality. On MMX-enabled computers, NetMeeting uses the MMX-enabled voice codecs to improve performance for voice compression and decompression algorithms. This will result in lower CPU use and improved voice quality during a call.

With NetMeeting 2.0, a user can send and receive real-time visual images with another conference participant using any video for Windows-compatible equipment. They can share ideas and information face-to-face, and use the camera to instantly view items, such as hardware or devices, that the user chooses to display in front of the lens. Combined with the video and data capabilities of NetMeeting 2.0, a user can both see and hear the other conference participant, as well as share information and applications. This H.323 standard-based video technology is also complaint with the H.261 and H.263 video codecs.

Multipoint data conferencing using T.120. Two or more users can communicate and collaborate as a group in real time. Participants can share applications, exchange information through a shared clipboard, transfer files, collaborate on a shared whiteboard, and use a text-based chat feature. Also, support for the T.120 data conferencing standard enables interoperability with other T.120-based products and services. The following features comprise multipoint data conferencing:

Application sharing: A user can share a program running on one computer with other participants in the conference. Participants can review the same data or information, and see the actions as the person sharing the application works on the program (for example, editing content or scrolling through information.) Participants can share Windows-based applications transparently without any special knowledge of the application capabilities.

The person sharing the application can choose to collaborate with other conference participants, and they can take turns editing or controlling the application. Only the person sharing the program needs to have the given application installed on their computer.

Shared Clipboard: The shared clipboard enables a user to exchange its contents with other participants in a conference using familiar cut, copy, and paste operations. For example, a participant can copy information from a local document and paste the contents into a shared application as part of a group collaboration.

File Transfer: With the file transfer capability, a user can send a file in the background to one or all of the conference participants. When one user drags a file into the main window, the file is automatically sent to each person in the conference; they can then accept or decline receipt. This file transfer capability is fully compliant with the T.127 standard.

Whiteboard: Multiple users can simultaneously collaborate using the whiteboard to review, create, and update graphic information. The whiteboard is object-oriented (versus pixel-oriented), enabling participants to manipulate the contents by clicking and dragging with the mouse. In addition, they can use a remote pointer or highlighting tool to point out specific contents or sections of shared pages.

Chat: A user can type text messages to share common ideas or topics with other conference participants, or record meeting notes and action items as part of a collaborative process. Also, participants in a conference can use chat to communicate in the absence of audio support. A "whisper" feature lets a user have a separate, private conversation with another person during a group chat session.

NetMeeting 2.0 Software Development Kit

This SDK enables developers to integrate this conferencing functionality directly into their applications or Web pages. This open development environment supports international communication and conferencing standards and enables interoperability with products and services from multiple vendors.

Also in the NetMeeting SDK are APIs to add non-standard codecs and to access ILS servers via LDAP, as well as an ActiveX™ control to simplify adding conferencing capabilities to Web pages.

For more information on the Microsoft NetMeeting 2.0 Software Development Kit, see http://www.microsoft.com/netmeeting/sdk.

Features of TAPI 3.0 and NetMeeting 2.0

TAPI 3.0 and NetMeeting 2.0 both support core IP Telephony capabilities. Each platform offers unique benefits: TAPI 3.0 seamlessly integrates traditional telephony with IP Telephony, providing a COM-based, protocol-independent call-control and data streaming infrastructure. NetMeeting 2.0 SDK supports T.120 conferencing and application sharing in addition to IP Telephony. Applications using TAPI 3.0 and the NetMeeting 2.0 API interoperate using H.323 audio and video conferencing.

When to use TAPI 3.0 and NetMeeting 2.0

Because TAPI 3.0 and NetMeeting 2.0 both support core IP Telephony capabilities (including support for H.323), developers may want to consider the following guidelines when choosing an API for their IP Telephony applications:

  • TAPI 3.0 This is the API to use if you are doing IP Telephony in your application. TAPI 3.0 is especially valuable in the world of client/server computer telephony integration, for combining IP Telephony with traditional telephony, and for IP multicast of voice and video.
  • NetMeeting 2.0 API This is the API to use if you are doing real-time collaboration and want to integrate voice, video, and data conferencing into your application. The NetMeeting API is useful for applications that want to integrate application sharing, whiteboard functionality, and multipoint file transfer with voice and video sessions.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

Remedy: Insert the MSDN Library CD into the CD-ROM drive.


Create conference announcement (with default attributes)

[This is preliminary documentation and subject to change.]

// obtain the ITConferenceDirectory interface

// create the conference announcement with default values
// (including the constituent conference blob)
BSTR Name = SysAllocString(L"MyConference");
pITConferenceDirectory->CreateConference(
    Name,
    &pITConferenceInfo
    );


Modify a known conference

[This is preliminary documentation and subject to change.]

// obtain the ITConferenceDirectory interface

// get the conference announcement (by name)
BSTR Name = SysAllocString(L"MyConference");
pITConferenceDirectory->GetConferenceAnnouncement(
    Name,
    &pITConference
    );

// modify attributes
BSTR NewName = SysAllocString(L"MyNewConference");
pITConference->put_Name(
    NewName
    );


Conference Directory Enumeration

[This is preliminary documentation and subject to change.]

// Create a conference directory component
CoCreateInstance(
    CLSID_ITConferenceDirectory,
    NULL,
    CLSCTX_INPROC_SERVER,
    IID_ITConferenceDirectory,
    (void **)&pITConferenceDirectory
    );

// point the conference directory component to the desired (ServerName, DirectoryPath
// Use default values for both
pITConferenceDirectory->Init(
    NULL,
    NULL
    );

// create an enumerator to enumerate all announcements in the directory
// the default filter is used
pITConferenceDirectory->_NewEnum(
    &pIEnumConference
    );

// enumerate announcements
do
{
    VARIANT ConferenceAnnouncement;

    // get the next announcement
    hr = pIEnumConference->Next(
                 1,
                 &ConferenceAnnouncement,
                 NULL
                 );
    if (S_FALSE == hr )
    {
        break;
    };

    // Process conference announcement
}

while (SUCCEEDED(hr));