540.50K

Category:

software

Tapi Tutorial

1.

TAPI Tutorial
Herman D’Hooge
Intel
Toby Nixon
Microsoft

Content
◆TAPI
Architecture
◆Assisted TAPI
◆Lines, Addresses, Calls
◆Basic TAPI Services
◆Media Streams on Calls
◆Multi-applications Features
◆Supplementary Services
◆Extensions
◆Developer Support
Slide 2

3.

TAPI: “Front-end” Interface
for Applications
PIM
Rolodex
Call Control
Integrated
Messaging
Desktop
Conference
Application
TAPI
◆Application
developers need only know about
TAPI’s API
◆TAPI hides specifics of telephone network and
connection hardware
◆Apps query TAPI to determine the capabilities
that are actually available

4.

TSPI: “Back-end” Interface
for Service Providers
◆Independent
telephony/hardware vendors only care
about TAPI’s SPI (TSPI)
◆TAPI eliminates multi-app considerations
◆Responsible for modeling its telephone hardware as
TAPI objects
TSPI
SP
SP
PSTN
SP
PBXn
SP
ISDN
Cellular
SP
Client
LAN
Server

5.

TAPI DLL
Runtime Code “in Between”
PIM
Rolodex
Call Control
TAPI
TSPI
PSTN
Desktop
Conference
Application
TAPI DLL
SP
SP
Integrated
Messaging
SP
PBXn
SP
ISDN
Cellular
SP
Client
LAN
Server

6.

TAPI DLL
◆Maps
between TAPI and TSPI
➢Is
the “plumbing” that routes requests &
replies between apps and SPs
◆Implements
internally
a number of TAPI functions
➢Multi-application
features
➢Address translation...
◆The
TAPI DLL is provided as a part of
Windows by Microsoft
◆Can be distributed freely with app/SPs
Slide 6

7.

TAPI Provides
Connection Independence
◆No
TAPI requirements on how PC
connects to Telephone network
➢direct
result of open desktop API/SPI
architecture
◆Flexibility
allows users to select on
➢functionality
➢computing
environment
➢telephony environment
➢economics
Slide 7

8.

TAPI Supports:
External Add-on
standard modem, or
proprietary module
●
serial
Switch
Slide 8

9.

TAPI Supports:
Integrated “CTI Phone”
Switch
Special CTI Phone
serial
Slide 9

10.

TAPI Supports: Mobile
Call Waiting
123-456-7890
AB
PCMCIA
Roam
1
2
3
4
5
6
7
8
9
0
#
*
SND
END
Slide 10

11.

Hayes AT TAPI
Service Provider Architecture
Application
TAPI
TSPI
Application
Application
TAPI DLL
Service Provider
Client PC
Hayes AT
(Extended)
seria
l
Slide 11

12.

TAPI Supports:
PC add-in Board
add-in board or
motherboard
Switch
Slide 12

13.

Add-in Board TAPI
Service Provider Architecture
Application
TAPI
TSPI
Application
Application
TAPI DLL
Service Provider
Client PC
Slide 13

14.

TAPI Supports: Client-Server
with Switch-to-Host Link
LAN
Host
link
Switch
Slide 14

15.

TAPI Supports: Client-Server
with Voice Server
LAN
Voice
Server
phone lines
Switch
Slide 15

16.

Client-server TAPI
Service Provider Architecture
App
API
App
App
App
API
TAPI DLL
SPI
App
App
TAPI DLL
SPI
Stub
Stub
Client PC
Client PC
LAN
Service Provider
(Server Part)
to switch
Server
Slide 16

17.

18.

Function Categories
Assisted Telephony
Full Telephony
Basic Services
Supplementary Services
Extended Services
Slide 18

19.

Assisted TAPI
◆Many
apps just want to place a call
➢tapiRequestMakeCall(
)
➢Trivial
to use, even from a macro
➢Use to telephony-enable existing apps!
◆Other
apps just want to place a call, then
process media (voice, fax, data...)
➢tapiRequestMediaCall(
➢Get
)
back TAPI_REPLY status messages
➢tapiRequestDrop(
)
➢Note:
use of tapiRequestMediaCall() is
discouraged as this function will not be
supported in future versions of TAPI.
Slide 19

20.

Assisted TAPI
◆Init:
Call Manager registers with TAPI as
“Assisted TAPI Request Recipient”
◆Assisted TAPI App passes phone# to TAPI
◆TAPI DLL passes request to Call Manager
◆Call Manager uses full TAPI to make call
➢Handles
Assisted TAPI
App
TAPI
details of call progress, etc.
Word
Processor
Call
Manager
Assisted TAPI
Request Recipient
TAPI DLL
Slide 20

21.

Assisted TAPI Example
◆Word
for Windows macro
➢Written
in “Visual Basic for Applications”
➢Can be bound to menu, key, button
➢Place a call to selected phone number
➢This is the whole macro:
Declare Function tapiRequestMakeCall Lib "TAPI.DLL"(
DestAddress$, AppName$, CalledParty$, Comment$) As Long
Sub MAIN
lResult = tapiRequestMakeCall(Selection$(), "", "", "")
If lResult <> 0 Then
MsgBox "Sorry, Call Manager unavailable"
End If
End Sub
Slide 21

22.

23.

Line Device
◆Physical
and logical resources providing
connection to telephone network
Examples:
➢1st-party
telephone line (wire)
➢Set of channels, e.g., ISDN B-channels can be
modeled as single line or multiple lines
➢3rd-party stations in a call center can be
modeled as one line per station or single line
with multiple addresses or combination
◆Service
Provider decides how to model
◆Apps “see” telephony as set of line devs
Slide 23

24.

Address (Phone Number)
◆Remote:
destination phone# of a call
◆Local: <line, address> pair identifies
origination point of a call
➢supports
3rd-party call setup
➢use dwAddressID instead of phone#
◆Address
assignment to lines can be
➢private
➢bridged-exclusive
➢bridged-new
➢shared
➢monitored
Slide 24

25.

Call (Telephone Call)
◆Corresponds
to a telephone call associated
with a particular
<line, address> endpoint
◆Comes into existence dynamically
◆Call States
➢Dialtone,
Dialing, Proceeding, Busy, Ringback,
Connected, OnHold...
◆Bulk
of TAPI interface operates on calls
➢Dial,
Drop, Hold, Transfer, Conference...
➢Call progress reporting, DTMF...
Slide 25

26.

Lines, Addresses, Calls
Relationships
lines
addresses
calls
general
POTS
call
PBXs...
waiting
Slide 26

27.

Lines, Address, Calls:
Object Handles
App1
hCall1
App2
hCall2
TAPI
TAPI DLL
hdCall
TSPI
Service
Provider
htCall
Slide 27

28.

29.

Basic Services
◆Making
and answering calls
◆Dropping calls
◆Status query (line, address, calls)
◆Call sharing across apps
(discussed later)
Slide 29

30.

Basic Services: Functions
lineAnswer
lineClose
lineConfigDialog
lineDeallocateCall
lineDial
lineDrop
lineGetAddressCaps
lineGetAddressID
lineGetAddressStatus
lineGetCallInfo
lineGetCallStatus
lineGetDevCaps
lineGetDevConfig
lineGetIcon
lineGetID
lineGetLineDevStatus
lineGetNewCalls
lineGetNumRings
lineGetStatusMessages
lineGetTranslateCaps
lineHandoff
lineInitialize
lineMakeCall
lineNegotiateAPIVersion
lineOpen
lineSetAppSpecific
lineSetCallPrivilege
lineSetCurrentLocation
lineSetDevConfig
lineSetNumRings
lineSetStatusMessages
lineSetTollList
lineShutdown
lineTranslateAddress
Slide 30

31.

Basic Services: Messages
LINE_ADDRESSSTATE
LINE_CALLINFO
LINE_CALLSTATE
LINE_CLOSE
LINE_LINEDEVSTATE
LINE_REPLY
Slide 31

32.

Dealing with Differing Network/
Device Capabilities
◆Capabilities
of network, HW, SPs can differ
widely (e.g., POTS .. PBX)
◆App cannot blindly assume that certain
functions are available
◆App must query capabilities
➢lineGetDevCaps()
➢Passed
◆App
lineGetAddressCaps()
on to SP, who returns info
can adapt its GUI and behavior
Slide 32

33.

Place Outbound Call
Address Translation
◆Canonical
Address Format
➢Is
“portable” format -- store in address book
and never changes:
+1 (206) 882-8080
◆Dialable
Address Format
➢Is
number actually dialed for current localtion
and telephone setup: 9,882-8080
◆Concept
of “User Location” and Translation
➢Select/configure
via Control Panel
➢Affects translation using
lineTranslateAddress()
Slide 33

34.

Place an Outbound Call
◆On
an open line - lineOpen()
◆lineMakeCall(),
lineDial()
➢Optionally
include originating address
(3rd party call control)
➢Destination address now or in lineDial()
➢Asynchronous operation - remaining parts of
the activity will be event-driven
◆On
LINE_REPLY, sync part is “done”
◆LINE_CALLSTATE to track call progress
◆When
“connected”, information can flow
over the call
Slide 34

35.

Asynchronous Events
◆Most
TAPI functions are asynchronous
➢Switch-related
functions return quickly,
proceed in background
➢Can take seconds to complete!
➢ASYNC_COMPLETION (SPI) and
LINE_REPLY (API) message on completion
➢RequestID ties reply to original request
◆Spontaneous,
unsolicited events
➢For
call progress, inbound calls...
➢LINE_ xxx messages sent to callback
procedure; parameters provide specifics
Slide 35

36.

Hang up a Call
◆If
app disconnects first
➢lineDrop()
◆If
remote end disconnects first
➢LINE_CALLSTATE
➢lineDrop()
◆On
“disconnected” message
to disconnect locally
LINE_REPLY
➢Call
typically transitions to “idle” state
➢Call handle still exists, for status queries
➢Clean up via: lineDeallocateCall()
Slide 36

37.

Inbound Call Handling
◆Select
line device(s) on which to receive
calls via lineOpen()
◆Register interest in notification for inbound
calls
➢privilege
none: just make outbound calls
➢privilege monitor: monitor (log) all calls
➢privilege owner: make outbound calls and be
notified of inbound calls of given media
Slide 37

38.

Answer a Call
◆LINE_CALLSTATE
➢provides
signals new call
call handle
◆lineGetCallInfo()
➢to
get at caller-ID, called-ID, UUI...
◆lineAnswer()
◆Track
status via LINE_CALLSTATE
➢When
“connected”, information can flow
over the call
◆Check
media mode LINE_MEDIAMODE
➢Handoff
if it is not the desired type
➢More on this later
Slide 38

39.

40.

PC-Telephony Integration:
Two “Processings”
◆Call
Processing
➢Call
setup and teardown
➢Hold, Transfer, Conference...
➢DTMF, Tones, Monitoring...
◆Media
Processing
➢Access
to a call’s content (e.g., voice path)
➢Record / playback sound over a call
➢Send / Receive all kinds of media...
Basis for Multimedia Integration
Slide 40

41.

Media Streams on Call
◆Use
the right API for the job
➢Use
TAPI to manage the connection
➢Use media stream-specific Windows API to
manage information stream on calls
➢Windows Wave API to access voice on
calls and phones
➢Other media-specific APIs to access their
media stream
◆“One
media type, one API”
➢No
need for TAPI to reinvent these APIs
Slide 41

42.

Media Streams on Calls
◆TAPI
provides call/media device map
➢Allows
app to view the “call” device as a
“media” device
◆lineGetID(hCall,
"wave/out"...)
➢Specifies
the call and media device class
➢Returns the “wave” device ID
corresponding to that call
➢SP maintains this correspondence
➢Use retrieved ID to open that specific device
by ID using wave API
➢waveOutOpen()
Slide 42

43.

Media Streams on Calls
◆1Use
TAPI to find the correct media device
◆2Then open the device through the media API
TAPI and Wave
Application
1
TAPI
Any Wave
Application
2
TAPI.DLL
MMSYSTEM.DLL
Wave API
Wave
Driver
Interface
TSPI
Service Provider
supporting
TAPI ...
Device
... and mciWave
Slide 43

44.

45.

Multi-Application Features
◆Lines
and Phones are Sharable Devices
➢Apps
can make outbound calls while others
listen for inbound calls
◆Cooperative
Sharing of Calls across Apps
➢Start
voice call in one app, receive fax over
same call using other app
➢Call handoff, grabbing a call
◆Routing
inbound calls to “right” app
➢Based
on media type (voice, data, fax...)
➢Multi-application toll saver (num rings)
Slide 45

46.

Inbound Call Example
Call Control
(UNKNOWN)
Modem
App
4
not voice
TAPI
TSPI
3
2
1
unknown
(voice, modem, fax)
unknown
(voice, modem, fax)
Incoming Modem Call
Fax
App
6
is modem!
5
unknown
(modem, fax)

47.

Media Type Determination
◆Based
on out-of-band information
➢e.g.,
ISDN signaling
➢distinctive ring, caller-ID...
◆Based
on inband information
➢may
require signal processing, probing,
heuristics
◆Based
on local address assignments
➢Different
address for each media type
Slide 47

48.

49.

Supplementary Services
◆“Advanced”
features associated with
PBXs, KTS, Centrex, ISDN
➢Conference,
Transfer, Forward, Hold, Park,
Pickup, Redirect...
➢UserUserInfo, Cellular, call parameters
◆DTMF/tones
generation and detection
◆Media monitoring and control
◆Phone device control
Slide 49

50.

Suppl. Services: Functions
lineAccept
lineAddToConference
lineBlindTransfer
lineCompleteCall
lineCompleteTransfer
lineForward
lineGatherDigits
lineGenerateDigits
lineGenerateTone
lineGetConfRelatedCalls
lineGetRequest
lineHold
lineMonitorDigits
lineMonitorMedia
lineMonitorTones
linePark
linePickup
linePrepareAddToConference
lineRedirect
lineRegisterRequestRecipient
lineRemoveFromConference
lineSecureCall
lineSendUserUserInfo
lineSetCallParams
lineSetMediaControl
lineSetMediaMode
lineSetTerminal
lineSetupConference
lineSetupTransfer
lineSwapHold
lineUncompleteCall
lineUnhold
lineUnpark
Slide 50

51.

Suppl Services: Messages
LINE_GATHERDIGITS
LINE_GENERATE
LINE_MONITORDIGITS
LINE_MONITORMEDIA
LINE_MONITORTONE
LINE_REQUEST
Slide 51

52.

Hold, Park, Pickup, Redirect
◆lineHold(),
➢for
lineUnhold()
hard hold
◆linePark(),
➢similar
lineUnpark()
to transfer, but no alerting
◆linePickup()
➢diverts
an call alerting elsewhere to the local
station
➢directed pickup and group pickup
◆lineRedirect()
➢diverts
a locally offered call to elsewhere
Slide 52

53.

Transfer
◆Consultation
Transfer
➢lineSetupTransfer()
➢create
consultation call
➢places active call on “transferhold”
➢lineSwapHold()
➢to
toggle between consult and held call
➢lineCompleteTransfer()
➢transfers
held call to consultation call
➢option to resolve transfer as 3-way conf
◆Blind
Transfer (single step)
➢lineBlindTransfer()
Slide 53

54.

Forward
◆Not
the same as transfer!!!
◆Instructs switch to route inbound calls to
alternate destination without answering
the call
◆lineForward()
➢busy,
noanswer, busynoanser,
unconditionally
➢selective forwarding based on who’s calling
-- specify as list of number pairs
Slide 54

55.

Call Completion
◆Provides
options when get busy or noanswer on outbound call
➢lineCompleteCall()
➢campon
(queues the call)
➢callback (return the call)
➢intrude (barge-in)
➢leave a message (predefined mesg)
➢lineUncompleteCall() to cancel
Slide 55

56.

Call Conference
◆Flexible
conference call setup
accommodates real-world differences
➢Add
consult call to regular two-part call
➢Resolve transfer as 3-way conference
➢Start with conference call directly
➢Conference two independent calls
◆A
conference call consists of
➢Conference
call handle to represent the
conference (bridge)
➢One member call handle for each “other”
endpoint - lineRemoveFromConf ()
Slide 56

57.

Phone Device
◆Abstraction
of phone set elements
➢Hookswitch
audio I/O devices
➢Handset, speaker, headset
➢Ringer, Display, Buttons and lamps
➢Download areas
◆API
provides query and manipulation of
a phone’s elements
◆Allows local audio input and output
Slide 57

58.

Phone Functions and Msgs
phoneInitialize
phoneShutdown
phoneNegotiateAPIVersion
phoneGetDevCaps
phoneOpen
phoneClose
phoneGetStatusMessages
phoneSetStatusMessages
phoneGetStatus
phoneGetID
phoneGetButtonInfo
phoneSetButtonInfo
phoneGetDisplay
phoneSetDisplay
phoneGetVolume
phoneSetVolume
phoneGetGain
phoneSetGain
phoneGetLamp
phoneSetLamp
phoneGetHookSwitch
phoneSetHookSwitch
phoneGetRing
phoneSetRing
phoneGetData
phoneSetData
PHONE_BUTTON
PHONE_CLOSE
PHONE_REPLY
PHONE_STATE
Slide 58

59.

60.

Extending the Interface
◆TAPI
provides hooks to allow equipment
vendor extensions
➢Does
not require Intel/Microsoft involvement
➢Does not require altering TAPI run-time
◆Key
characteristics
➢Apps
format commands as data
➢TAPI passes data through to provider
➢A way to avoid “colliding” extensions
(Extension IDs, EXTIDGEN.EXE)
◆Apps:
use extensions with caution!!
Slide 60

61.

62.

Developer Support
◆Internet:
ftp.microsoft.com
\developr\tapi
◆Administrative: [email protected]
◆CompuServe: GO WINEXT library 3
◆Microsoft Developer Network CD-ROM
1-800-759-5474
◆Windows 95 SDK/DDK
◆Windows NT SDK beta: H2'95
◆Misc TAPI product info: GO INTELA
◆TAPI "bakeoffs": interoperability test
◆TAPI support in future MFC -- tools
Slide 62

63.

English Русский Rules