Toshiba TSPI Description Application Bulleti V2.26

Computer Telephony Integration

Application Bulletin

AB50-0012
September 1, 1997

Purpose

The following technical material is used for software engineers and programmers developing
third party TAPI applications with Toshiba telephone systems.

Introduction

Microsoft® Windows® Telephony is a component of Windows Open Services Architecture.
This architecture provides for the operation of telephony services when connected to many
different telephone swit ches. Therefore, an a pplication ne eds to kno w only the def inition of t he
API and not its implementation.

The telephony model supplies a DLL component, called TAPI.DLL. This component resides
between the Telephony API called by appl icat ions an d the Telephony SPI implement ed for t he
specific switch to which the PC is connected. The software applications call TAPI functions
that are managed by TAPI.DLL and routed to the Service Provider Interface (e.g., Toshiba’s
DKT SPI) for execution. The relationship between these components is shown in Figure 1.

4170117

TSPI Description V2.26

Microsoft Windows PC

Strata DKT

RS-232 Link

RPCI to COM Port

2046

Figure 1 The Telephony API Model and the Strata DK

Toshiba America Information Systems, Inc.

9740 Irvine Bl vd., Ir vin e, CA 92618-1697 [phone]

TAPI

Service
Provider

Telecommunication Systems Division

TAPI

Application # 1

TAPI

DLL

(Windows)

TAPI

Application # 2

1 of 20

AB50-0012

TSPI Description V2.26

The Telephone Applications Programming Interface (TAPI) was a joint development of
Microsoft and Intel
types of telephone systems. The standard allows software developers to create applications
without having to worry about how the telephone network interface functions. This interface
provides thre e levels of service: Basic, Supplementary, and Extended .Levels of Service

Levels of Service

Basic

Basic Services are centered around Plain Old Telephony Service (POTS) including a set of re­defined call states and information messages which pass events to the application. Features of
POTS include answering calls, making calls, numbering plans to support dialing, and the
ability to translate numbers based upon type and location of the user.

Supplementary

Supplementary Services provide additional features commonly found in most PBX’s. These
include call features such as Call Transferring, Forwarding, Conferencing, Hold, Park, and
Pickup. Additional services are defined for interfacing Media Services such as providing
interfaces for fax, modems, voice response, and tone detection/generation. Release 2.0 of the
TAPI specification includes third party call control services for Automatic Call Distribution
(ACD) and future Asynchronous Transfer Mode (ATM).

®

to provide a standard method of connecting Windows based PCs to all

al

i

Extended

Extended Services provide a method to access features and services beyond the Basic or
Supplementary Services. TAPI provides for the passing of messages directly between the
telephone system and the application. TAPI only passes these messages directly to either end
and does not take action or make interpretations of them. The application, therefore, is
responsible for the complete interaction of the feature or service provided.

Interfaces

ary an

The Windows Open Syste m Architecture pr ovides two interfaces for Telephony Devices. The
TAPI interface provides for the control of calls using a well defined interface and the audio
connection is handled in what Microsoft calls a Media Stream. To allow for a standard
interface for playing and recording messages, interfacing fax, modem or other devices uses a
separate application interface. The WAV API is a common interface that can provide these
services in an open manner that can be controlled using the TAPI interface.

Strata DK’s TSPI Model

rel

P

For the application’s developer, the Microsoft standard provides for two device classes: the
line device and the phone devic e. Any physical telephonic device recognized by TAPI fits into
one of these two classes, and can be treated in a consistent and reliable manner. Strata DK
TSPI only supports the line device class. The phone class is for telephone devices controlled
by the applicati on.

min

i

d Confident

2 of 20

Strata DK I&M August 1997

TSPI Description V2.26

Line Device Model

The Strata DK TSPI models its interface as a single-line device with multiple addresses, each
having no more than one call appearance. The specific capabilities of the line device and each
of the addresses are explained under the function description for lineGetDevCaps and
lineGetAddressCaps.

Phone Device Model

At present, the DKT TSPI does not support the phone device model.

The DKT TSPI Call State Flow

The Toshiba TAPI Service Provider V2.26 provides two options for call state flow. Standard
operation has a call state flow shown in Figure 2. When the shared line operation is selected,
the call state flow is shown in Figure 3.

AB50-0012

al

i

I-Ring

I-Use

Deallocate Call
Handle

Idle

Figure 2 Call State Flow

C-Ring
C-Hold

Allocate Call
Handle

min

i

Dial Tone

Busy

Offering

BusyLED

OFF

I-Use

d Confident

LED OFF

ary an

Ringback

I-Use

Hold

Busy

ConnectedStart

I-Hold
E-Hold

2045

rel

P

Strata DK I&M August 1997

3 of 20

AB50-0012

y

TSPI Description V2.26

Dial Tone

I-Use
Busy

Deallocate Call
Handle

Idle

Figure 3 Call State Diagram for Shared Line Appearance

Table 3-1 Call State Descriptions

Call State LED Flash Color DK16e & DK424 R3

I-Ring
C-Ring

Allocate Call
Handle

Busy

Unknown

LED OFF

Offering

Busy

I-Use

Busy

C-Hold

LED OFF

Ringback

I-Use

Hold

I-Hold

ConnectedStart

2432

All Other

stems

S

al

i

Idle Steady Off Idle Idle
Transferred Calls (1Hz) Green T-Ring
Incoming Call 1 (10Hz), 1 Off Green I-Ring I-Ring
Hold Recall 1 (2Hz), 1 (10Hz) Green H-Recall H-Recall
I-Hold (4Hz) Green I-Hold I-Hold
Transf er Ho ld (10Hz) Green T-Hold T-Hold

d Confident

ary an

Exclusive Hold (10Hz) Green E-Hold E-Hold
Current Lin e In-Use* I-Use Rate Green I-Use I-Use
Common Hold 3/4 On, 1/8 Off Red C-Hold
Common Hold (1Hz) Red C-Hold C-Ring, T-Hold
Incoming Line Ring (1Hz) Red I-Ring
Common Ring (2Hz) Red C-Ring

min

i

rel

Busy Steady On Red Busy Busy

P

*I-Use rate is generated in the phone. The cycle consists of 2 seconds on followed by 1/8
second off, 1/8 second on, 1/8 second off state.

4 of 20

Strata DK I&M August 1997

TSPI Description V2.26

System Messages

An application receives information in two ways: solicited and unsolicited. Solicited
information is req uest ed by the application through a function call such as lineGetDevCaps or
lineGetAddressCaps. Unsolicited information arrives in the form of messages. Often, the two
mechanisms are used together, as when an application receives a LINE_CALLSTATE
message, after which it checks the infor mation contai ned in th e LINECALLINFO s truct ure b y
calling lineGetCallInfo.

Strata DKT TSPI supports the following messages providing unsolicited information:

LINE_CALLSTATE

Sent to an application to notify it about changes in a call’s state.

LINE_LINEDEVSTATE

Sent to the application to notify it about changes in the line status. This message indicates
which status item has changed.

LINE_ADDRESSSTATE

The Service Provider follows with this callback message giving changes to the state of any
address.

AB50-0012

al

i

LINE_CALLINFO

A callback message that notifies of additional information about the call.

LINE_REPLY

Messages generated for all asynchronous requests. Toshiba DKT TSPI always uses
lineMakeCall in this asynchronous manner.

LINE_NEWCALL

A message to notify the application of a new call event arriving.

Startup and Shutdown of TAPI

lineInitialize

An application re gis ters a TAPI connection b y callin g this functio n. This fun ction is not passe d
through to the TSPI but handled by TAPI.DLL. One of the main purposes is to establish a
pointer to the application’s callback function to allow unsolicited messages to be registered.
Two pieces of information is retur ned to the appli cation: an appl icat ion ha ndle a nd the number
of available line devices. Strata DK TSPI supports multiple line devices.

lineShutdown

rel

min

i

ary an

d Confident

P

Strata DK I&M August 1997

When the application is done, this command releases the resources and the TAPI environment
is disconnected.

5 of 20

AB50-0012

g

lineNegotiateAPIVersion

This function is used to negotiate the API version number to used. The application provides
the range of versions it is compatible with and TAPI.DLL in turn negotiates with the TSPI to
determine which version range it supports.

lineOpen

TSPI Description V2.26

This function opens the specified device ID for the purpose of monitoring or control by the
application. Opening the line returns the handle for the device. The application can then use
this handle to answer inbound calls, make outbound cal l s, or moni tor ca ll activities on the l i ne
for logging purposes. The application should query the capabilities of the line, (using
lineGetDevCaps) before opening the line device. Upon opening the line, a serial port will be
allocated and initialized.

lineSetStatusMessages

This operation allows an application to specify which notification messages the service
provider s hould genera te for events relat ed t o t he s tatus chang es for the s pec if ie d li ne or an y of
its addresses.

lineGetStatusMessages

This function queries the TSPI for current status messages.

lineClose

This function closes the specified open line device after aborting all outstanding calls and
asynchronous operations on the device.

Receiving Information

al

i

d Confident

lineGetDevCaps

This function queries a specified line device to determine its telephony capabilities. It is
important for an application to call this function before opening the line device. This allows
the application to determine which of possibly several line devices to use. Returns the
supplementary and extended capabilities of a given line device as a data structure of type
lineDevCaps:

min

i

dwProviderInfoSize
dwProviderInfoOffset

rel

P

6 of 20

dwSwitchInfoSize
dwSwitchInfoOffset

dwPermanentLineID This field will contain the permanent device ID, as

ary an

Field Name Settin

The memory area referenced by these fields will
contain the NULL-terminated string describing the
service provider. The Strata DK service provider is
“Toshiba DKT TSPI”.

This memory area is not used by the Toshiba DKT
TSPI.

found in TELEPHON.INI.

Strata DK I&M August 1997