Microsoft Windows CE .NET 4.

2 --- Telephony API

Microsoft® Windows® CE .NET supports a subset of the Microsoft Telephony API

(TAPI) 2.0 and some features of TAPI 2.1. TAPI is a set of APIs that simplify and abstract
the details of making telephony connections between two or more devices. TAPI abstracts
call-control functionality to allow different, and seemingly incompatible, communication
protocols to expose a common interface to applications through its support of telephony
service providers (TSPs).

Windows CE ships with one TSP, the Unimodem service provider, which supports AT-
command-based modems. Windows CE supports installable service providers, which
enables independent software vendors (ISVs), original equipment manufacturers (OEMs),
and independent hardware vendors (IHVs) to add additional TSPs under TAPI — for
example VoIP, such as H323 and session initiation protocol (SIP), Integrated Services
Digital Network (ISDN), cell phones, and so on.

Windows CE .NET, through the addition of TAPI 2.0, brings inbound call support for
both data and voice. Supplementary services (call forward, hold, park, conferencing, and
so forth) and support for multiple calls are added also. In addition, support for call-center
management is enhanced, with modeling of predictive dialing ports and queues,
associating data with calls, controlling message waiting lights, and controlling music on
hold and centralized event timing. Furthermore, application message notification is
improved significantly in TAPI 2.0. As with previous versions of TAPI, the availability of
these features depends upon the underlying TSP and hardware.

You can use TAPI 2.0 to bring telephony functionality to any Windows CE–based
application, such as a database manager, spreadsheet, word processor, personal
information manager, or any other application that can benefit by sending and receiving
data through the telephone network.

TAPI 2.0 provides a set of tools for incorporating the following features into your
application:

• Connect directly to the telephone network, instead of relying on a separate

communications application.
• Dial telephone numbers automatically.

With TAPI 2.0, a user can make a telephone call through a Windows CE–based device,
set up a conference call, or connect to a remote host computer to download data at
predetermined times. TAPI applications also can determine whether or not the mobile
terminal supports advanced features, such as call waiting or faxing.

The Windows CE .NET implementation of TAPI 2.0 supports a set of APIs that let you
create various types of applications that implement telephony functionality. Windows CE
also supports the TAPI telephone device API set.

PRASHANT SHARMA : [email protected] 1

The Tapi.dll library file exports all of the TAPI functions that can be used to create TAPI
applications. TAPI function prototypes, as well as TAPI structures, are defined in the
Tapi.h header file.

Asynchronous functions return either a TAPI error code or a request identifier. When the
request is completed, the application receives a LINE_REPLY message that contains the
result code for the operation and the request identifier.

General Architecture of TAPI 2.0

The following illustration shows the general architecture of TAPI 2.0 for Windows CE
.NET.

In the TAPI 2.0 architecture that is implemented in Windows CE, the Tapi.dll library file
gets loaded in the Device.exe protected server library (PSL). Tapi.dll exports the TAPI set
of functions that are supported in Windows CE. An application first links to the
Coredll.dll file. When an application calls a TAPI function, Coredll.dll thunks the call to
Tapi.dll in the process context of Device.exe. TAPI service provider DLLs are loaded by
TAPI and executed also in the process context of Device.exe.

When an application that is based on Windows CE calls a TAPI function, the Tapi.dll
library file validates and arranges function parameters, and then forwards them to the
appropriate service provider. A service provider can provide different levels of the TSPI:
basic, supplementary, or extended. For example, a simple service provider might provide
basic telephony service, such as support for outbound calls, through a Hayes-compatible
modem, while a custom service provider that has been written by a third-party vendor
might provide a full range of inbound and outbound call management.

Underneath the TSPI layer, the service provider can use any system functions or other
components that are necessary to work with kernel-mode components and services that
are designed by OEMs, as well as standard devices, such as serial and parallel ports, to
control external locally attached devices. The service provider also can access network
services (such as Windows Sockets) for client/server telephony.

Line Device

PRASHANT SHARMA : [email protected] 2

The Windows CE .NET implementation of TAPI 2.0 provides support for line devices. A
line device is a physical channel that comprises 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 exactly to 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 that 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.

TAPI 2.0 requires that every TAPI-capable line device support all of Basic Telephony
Services. If an application needs to use capabilities beyond those of Basic Telephony
(namely Supplementary or Extended Telephony Services), it first must determine the
telephony capabilities of the line device, which can vary according to network
configuration (client versus client/server), hardware, service-provider software, and the
telephone network.

The lineGetDevCaps function queries a specified line device to determine its telephony
capabilities. The returned information is valid for all of the addresses on the line device.
The dwExtVersion parameter of lineGetDevCaps indicates the version number of the
extension information that is requested. If the version number is zero, no extension
information is requested; if it is nonzero, it holds a value that was negotiated already for
this device with the lineNegotiateExtVersion function. The service provider should fill
in device-specific and vendor-specific extended information, according to the extension
version that is specified.

Phone Device

The Windows CE .NET implementation of TAPI 2.0 also supports telephone devices. A
telephone device is a device that supports the telephone device class and includes some or
all of the following elements.

• Hookswitch/Transducer: A means for audio input and output. TAPI 2.0

recognizes that a telephone device can have several transducers, which can be
activated and deactivated (taken off-hook or placed on-hook) under application or
manual user control. TAPI identifies three types of hookswitch devices that are
common to many telephone sets:

Handset The traditional mouth-and-ear-piece combination that must be lifted

manually from a cradle and held against the ear of the user.

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

PRASHANT SHARMA : [email protected] 3

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

A hookswitch must be off-hook to allow audio data to be sent to and 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 telephone device
might be able to ring in a variety of modes or patterns.
• Display: A mechanism for visually presenting messages to the user. A telephone
display is characterized by its number of rows and number of columns.
• Telephone Buttons: An array of buttons. Whenever the user presses a button on
the telephone 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 that
are available on the telephone device, minus one. Each button belongs to a button
class. Classes of buttons include call appearance buttons, feature buttons, keypad
buttons, and local buttons.
• Lamps: An array of lamps, such as light-emitting diodes (LEDs), that are
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 telephone device where instruction code or data
can be downloaded to and uploaded from. The downloaded information would
affect the behavior of (or, in other words, program) the telephone device.

TAPI 2.0 allows an application to monitor and control elements of the telephone device.
The most useful elements for an application are the hookswitch devices. The telephone
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 telephone); and
perhaps a display, although the display of the computer is more capable. The application
writer is discouraged from directly controlling or using telephone lamps or telephone
buttons, because lamp and button capabilities can vary widely among telephone sets, and
applications can become tailored quickly to specific telephone sets.

There is no guaranteed core set of services that are supported by all telephone devices, as
there is for line devices (the Basic Telephony services). Therefore, before an application
can use a telephone device, the application first must determine the exact telephony
capabilities of the telephone device. Telephony capabilities vary with the configuration
(client versus client/server), the telephone hardware, and the service-provider software.
An application determines the device capabilities of a telephone device by calling the
phoneGetDevCaps function. The device capabilities of a telephone indicate the elements
that exist for each telephone device that is present in the system and what its capabilities

PRASHANT SHARMA : [email protected] 4

are. Although strongly oriented toward real-life telephone sets, this abstraction can
provide a meaningful implementation (or subset thereof) for other devices, too. For
example, take a separate headset that is connected directly to and controllable from the
computer and operated as a telephone device. Hookswitch changes can be triggered by
detection of voice energy (when off-hook) or a period of silence (when on-hook); ringing
can be emulated by the generation of an audible signal into the headset; and a display can
be emulated through text-to-speech conversion.

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

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

Establishing a Modem Connection

An application that is based on Windows CE and that uses a modem must be able to
handle tasks such as initializing the modem, opening the line, dialing a telephone number,
closing the line, and disconnecting when the session is complete.

To create a modem connection by using TAPI

1. Call the lineInitializeEx function to initialize TAPI.

2. Call the lineOpen function to open the line.
3. Call the lineMakeCall function.
4. Call the lineGetMessage function, as needed, to receive status messages from
TAPI.
5. Call the lineDeallocateCall function.
6. Call the lineClose function to close the line connection.
7. Call the lineShutdown function to end the session.

The lineInitializeEx function returns the number of line devices that are available. If the
LINEINITIALIZEEXOPTION_USEEVENT message is specified, no callback function
is required, and you can use the lineGetMessage function to retrieve a TAPI message.

When the call is set up, TAPI returns a LINE_REPLY message. This message indicates
only that the call has been established at the local end, which is indicated perhaps by a
dial tone. The parameters for the lineMakeCall function are the telephone number to
dial, the handle to a line device, and other parameters. As the connection process
proceeds, TAPI returns a series of LINE_CALLSTATE messages to indicate the progress

PRASHANT SHARMA : [email protected] 5

of the connection; for example, dial tone and ringing. When the connection is completed,
TAPI returns a LINECALLSTATE_CONNECTED message.

During data transfer, TAPI continues to manage the connection, but the application
handles data transmission and reception. When the transmission is complete, TAPI
returns a LINE_CALLSTATE message, such as one that indicates that a remote
disconnect has occurred.

Telephony Service Provider Interface

TAPI 2.0 requires a device that is based on Windows CE to have not just a TAPI-
compliant application, but also a TSPI. This interface talks directly to the hardware to
convert TAPI service requests into commands that are "understood" by the hardware. The
TSPI is responsible for managing the data from TAPI to control line devices and
telephone devices.

In Windows CE, a TSPI module is a DLL that provides communication services over a
telephone network through a set of exported functions that are called by TAPI. The Tspi.h
header file should be used only in conjunction with the Tapi.h header file. Most
parameters are passed through from corresponding procedures in Tapi.h.

TAPI supports the lineAddProvider function, which installs a new TSPI into the
telephony system. When an application calls this function, TAPI verifies that it can access
the service provider. If the function fails, or if the DLL or the service provider cannot be
found, the provider is not added to the telephony system. If the function succeeds, and if
the system is active, TAPI starts the new service-provider DLL.

Any number of service providers can be installed on a computer, as long as the service
providers do not attempt to access the same hardware device at the same time. The
association between the hardware and the service provider is indicated in the registry.
Some service providers might be capable of accessing multiple devices. In some cases,
installation might require a device driver along with the service provider.

Applications use the TAPI functions to determine the services that are available on the
device. TAPI identifies available service providers and the services that are supported,
and provides this data to applications. In this way, any number of applications can request
services from the same service provider; TAPI manages all access to the service provider.

A TSP must support the TSPI_provider functions that are called by TAPI. A TSP can
choose not to support almost any TSPI function.

In Windows CE, the only required DLL export function from a TSPI DLL is the
TSPI_lineGetProcTable function. This function is used to return to TAPI the addresses
of the interface functions of the TSP.

LONG TSPIAPI TSPI_lineGetProcTable

(

PRASHANT SHARMA : [email protected] 6

 LPTSPI_PROCS *lplpTSpiProcs
);

The lplpTSpiProcs parameter is a pointer to the TSPI_PROCS structure, which is

defined in the Tapicomn.h header file. TSPI_PROCS contains the table of function
addresses that is returned when the TSPI_lineGetProcTable function is called.

Some of the TSPI functions, such as TSPI_lineCompleteCall, are not called by TAPI.
Windows CE still supports these functions to maintain backwards compatibility with
older versions of the operating system.

TSPI Functions

The following list shows the different types of TSPI functions.

TSPI Callback Functions

TSPI Line Device Functions

TSPI Phone Device Functions

TSPI Service Provider Functions

TAPI Registry Settings

The registry stores information necessary to configure the system for applications and
hardware devices. The registry also contains information that the operating system
continually references during operation.

To enable multiple Telephony Service Providers (TSPs), the registry values that are
specific to a service provider are located in a subkey of the device. When a new device
driver is loaded, the device manager looks for a subkey that contains the TSP value and
then notifies Telephony API (TAPI). TAPI then loads the service provider and passes a
pointer to its specific values.

Note The default registry values vary depending on which features are included in your
platform. For more information, see Default Registry Settings.

PRASHANT SHARMA : [email protected] 7