july 9, 1997copyright 1997, grant schenck software1 tapi 2.0/2.1 genoa technology san jose,...

July 9, 1997 Copyright 1997, Grant Schenck Software 1

TAPI 2.0/2.1

Genoa Technology

San Jose, California

July 9th, 1997

Grant Schenck,Grant Schenck Software

[email protected]


Introductions• Genoa Technology

• Grant Schenck

• Attendees– Name, Company

– TAPI and Other CTI Experience

• App and/or TSP development?

• TAPI Versions?

• Programming Language?

– What do you hope to get from the course?


What Will be Covered• This course will cover TAPI versions 2.0 and

2.1 with an emphasis on development issues.

• What won’t be covered in-depth– Previous versions of TAPI (1.3 & 1.4.)– Media streams.– Phone devices.


Contents• Introduction

– What do you use TAPI for?– TAPI Architecture– TAPI 2.1 Enhancements

• Basic Concepts– TAPI "Objects"– App and TSP responsibilities

• Getting Oriented– TAPI App and TSP views– Call States– Handles

• Hold Call Example– Application and TSP Hold Support


Contents• Structures & Message

– Line, Address and Call Structures– Structure Update Messages

• Functional Areas– Basic Services: MakeCall, Answer, etc.– Supplemental Services

• Hold, Transfer, Conference, etc.• Background Functions• Extended Functions

• Supporting TSP Functions– Sync and Async– Initialization/Shutdown– Handling lines– Handling Calls


Contents• The TUISPI DLL

• Proxy Request Handlers (ACD Support)

• TAPI 2.1 Client Management DLLs

• Advanced Topics– Tips

– Modeling Environments

– Development Issues

– Debugging

• Summing Up


Introduction


What do you use TAPI for?• TAPI is used in a Windows environment to

control telephony resources.

• TAPI attempts to allows applications to treat telephony devices more or less generically without regard for the underlying hardware.

• TAPI applications fall into two basic camps:– Call Control applications

– Media Control applications

• However, depending on hardware support, some TSPs handle both aspects, i.e., predictive dialing, wave file through PBX, etc.


Call Control Applications• First party

– PIMs– Agent Support - Screen pop– Power Dialing, Single Seat Dialers– GUI access to complex PBX operations.– etc.

• Third Party– ACD– Call Loggers– Operator Console– etc.


Media Control Applications• Currently mainly first party oriented

• Examples include:– Answering machine apps

– Auto attendant apps

– Data exchange apps (i.e., traditional modem apps)

– Predictive Dialers

– etc.


First Party vs. Third Party C.C.• First Party Call Control

– Ability to monitor and control just the phone associated with a single (usually PC equipped) user.

– Can be provided via a local TSP with a physical connection to a phone, a modem, a network link, etc.

– Can also be provided by REMOTE.TSP (in 2.1.)

• Third Party Call Control– Allows an application to monitor and control multiple

devices.

– PC running the application is not necessarily associated with a particular device but could be, i.e.,

• An operator application.


Where TAPI Fits In CTI• TAPI isn’t used to build switches but it could

be built into one.• Competitors include:

– TSAPI - Novell/ATT– CSTA - ECMA– JTAPI - Java (Sun) Telephony– CT Connect - Dialogic– etc... everyone wants to build middleware!


TAPIVersion

AppType(s)

TSPType(s)

OSType(s)

1.3 16 bit 16 bit Win 3.1

1.4 16/32 bit 16 bit Win ‘95

2.0 16/32 bit 32 bit NT 4.0

2.1 16/32 bit 16/32 bit32 bit

Win ’95 NT 4.0

TAPI Versions


TAPI Architecture (2.0)

16-bit Process

16-bit TAPIApplication

32-bit Process

TAPI.DLL(16-bit thunk)

TAPI32.DLL

32-bit TAPIApplication

TAPI32.DLL

32-bit TAPI Service Process

TAPISRV.EXE

UNIMODEM.TSP

UNIMODEM.SYS(kernel mode driver)

Telephony ControlPanel, Dialing

Properties, etc.

Registry

Diagram Copyright (c) 1997, Microsoft Corporation


Types of TAPI Programs• Applications, 16 & 32 bit.

• TAPI Service Providers (TSP), 16 & 32 bit.

• TAPI 2.0 Request Handlers.

– Server based apps for ACD Support.

• TAPI 2.1 Client Management DLLs.

– Server based DLLs which can modify or rejecting function request from clients.

• But not server based applications.


TSP Packaging• A TSP consists of two required pieces:

– The TSP DLL exporting TSPI_xxx functions.– The UI DLL exporting TUISPI_xxx functions.

• When UI request are made, TAPI will call the UI DLL.

• The UI DLL can communicate with the TSP.

– Both DLLs can be combined in the same TSP file. This would be useful if the nature of your TSP is that it will never be remoted.

• A TSP may also use other programs (Device Drivers) or servers (CTI Server, PBX interface, etc.)


TSP Physical Models• PBX CTI Link

• Modem Based

• Phone Based

• Voice Board Based


TAPI 2.1 Enhancements• TAPI 2.1 allows an NT Server to share its lines

with Win '95 and NT clients.

• TAPI 2.1 supports Client Management DLLs.

• Limitations– TAPI 2.1 will not remote media streams.

– TAPI 2.1 places no restrictions on the sharing of phone devices. All applications see all phone devices.

– TAPI 2.1 does not support "spontaneous" UIs.

– A TAPI 2.1 client can only attach to the lines hosted by one TSP running on one NT Server.

• Client must also be granted access using TCMAPP.EXE.


TAPI 2.1 ArchitectureSERVERMachine

TAPIApplication

TAPI32

TAPISRV

REMOTESPServiceProvider

TAPISRV

ClientManagement

DLLs

CLIENTMachine



TAPI 2.1 Components• TAPI 2.1 includes the following components:

– REMOTE.TSP

• Client based TSP that gives clients views of lines hosted on the server.

– TCMAPP.EXE

• Utility to set user-to-line permissions.

– TCMSETUP.EXE

• Utility to install and configure client/server features of TAPI 2.1 on both the server and on the clients.

• Allows installation of Client Management DLLs.


TAPI Resources• Online

– TAPI 2.1 is available for download at:• http://www.microsoft.com/ntserver/info/tapiannounce21.htm

– TAPI docs, tools and samples, i.e., ESP, ESP32, ENUMTAPI, TAPICOMM, TB13, TB14, others

• FTP://ftp.microsoft.com/developr/TAPI

– August, 96 (#8), "To Learn About the Voice Modem Extensions for Windows 95, Press 1 Now!"

• ftp://ftp.microsoft.com/developr/MSJ/MSJAug96.zip

– Development information about Unimodem and Unimodem/V can be found in:

• FTP://ftp.microsoft.com/developr/drg/modem/modemdev.exe

– The Unimodem/V upgrade can be downloaded from:• FTP://ftp.microsoft.com/softlib/mslfiles/unimodv.exe


• Online Continued– TAPI General Web Page at MS

• http://www.microsoft.com/ntserver/communications/tapi.htm

– Microsoft news server "msnews.microsoft.com"• microsoft.public.win32.programmer.tapi

– Compuserve's WINEXT Forum.

• TAPI 2.0 API are both covered in MSDN (4/97) and MSVC 5.0 as well as MS Web Site. Look under – Windows Base Services\Files and I/O\TAPI & following

TSPI section.

TAPI Resources


TAPI Resources• Tools

– TAPI Test, TAPI Browser (TB20.EXE), Repeater, ESP32, DBWIN32.

• Books– Multimedia & ODBC API Bible, by Richard J. Simon,

Waite Group Press

– MAPI, SAPI, & TAPI Developers Guide, by Michael Amundsen, Sams Publishing

– Communications Programming for Windows 95, by Charles Mirho, Microsoft Press


Basic Concept


The Big Picture

Application 1 Application n

TAPI

TSP 1 TSP m


TAPI "Objects"• There are five principle objects in TAPI:

– Provider,– Line Device (one or more per provider), – Address (one or more per line), – Call (zero or more per address) and– Phone Device (zero or more per provider)

• TAPI docs don't really make a distinction based on this breakdown. For example:– Apps aren't really aware of provider functions.

– Line, address and call functions are all linexxx().


TAPI Object Hierarchy

L in e 0

A d d ress 0

C a ll 1 2 3 C a ll 1 2 4

A d d ress 1 A d d ress m -1

L in e 1 L in e n -1

P rovid er


Application Responsibilities• A TAPI Application uses the TAPI APIs to:

– Create, destroy, and configure these objects.

– Monitor and query the state of these objects.

– Manipulate these objects to cause possible state changes (as well as actual telephony changes).

• A TAPI application will use one or more line devices hosted by one or more TSPs.


TSP Responsibilities• A TSP does the following for each of the

object types:– Maintains their state.

– Provides current state information to TAPI and applications when requested.

– Notifies TAPI and applications when object states change including changes caused by external events.

– Supports requests to manipulate objects which may cause state changes.

• At minimum, a TSP will support one line devices with at least one address and capable of supporting at least one active call.– i.e., Unimodem when running with one modem.


Provider• A TSP is a single Provider.

• TSP Provider functions are called by TAPI to:– Install and remove the TSP.

– Initialize, shutdown and configure a TSP.

– Assist a TSP in dynamic line creation.

• Provider object doesn't have any significant state or notification.


Line• Lines usually represent a PBX extension or

phone.

• Switch based TSPs may also model outside lines, hold points, queues, etc. as TAPI lines.

• Lines can be closed or open.– When closed they are referenced by a device ID.– When open they can also be referenced by a handle.

• Line functions are called to:– Open, close and configure lines.– Monitor and query state information.– Create and manipulate calls.


Address• Addresses usually represent a dialable

number.

• Addresses can be on a line that is open or closed.– When closed they are referenced by the line device ID

and the address ID (a number from 0 to one less then the number of addresses on the line.)

– When the line is open the line can be referenced by a combination of the line handle and the address ID.

• Address functions are called to:– Monitor and query state information– Create and manipulate calls.


Call• Calls are dynamic and are created:

– In response to TAPI functions.

– By the TSP in response to an external event such as an incoming call or a phone going off hook.

• Calls are only referenced by a call handle.

• Call functions are called to:– Monitor and query state information.

– Manipulate calls.


Phone• Phones Devices are simpler then lines

• Phones, like lines, can be open or closed.– When closed they are referenced by a device ID.– When open they can also be referenced by a handle.

• Phone functions are called to:– Open, close and configure Phones.– Query state information.


TAPI Functions• TAPI functions are directed at one of the

above objects. For example:– To make a call on a line, an application calls

lineMakeCall() passing the handle of an open line.

• To make a call on an address an application would still call lineMakeCall(), but would also pass an address ID.

– To query the static device capabilities of an address, an application calls lineGetAddressCaps() passing the Device ID of the line and the Address ID on that line.

– To put a call on hold an application calls the lineHold() function passing a call handle.

• TAPI generally passes functions on to the TSP that controls the line.


Getting Oriented


Two Views of TAPI

• TAPI can be viewed from two perspectives– The application communicating with Windows

– The TSP communicating with Windows

• We will start by looking at TAPI from the Application perspective.


App View - Functions• Applications make TAPI API function calls

to control calls in Windows

• There are two types of TAPI function calls– Synchronous functions, which immediately return

a success or failure execution result.

– Asynchronous functions, which run in the background. Windows lets you know at a later time if the function executed successfully (Request ID and LINE_REPLY.)


Function Parameters• Each time a TAPI function call is made, the

application must do two things:– Fill in values for parameters that Windows needs to

complete the function execution

– Specify memory locations where Windows can store the results of the function execution (such the negotiated API version)


Application View - Messages• Messages are sent to the application by

Windows to indicate progress and alert the application of changes to the environment

• Some of these messages inform the application that status structures have been updated (think of a data base!)


App to TAPI - OutboundAPPLICATION

lineInitializeEx()

lineOpen()

lineMakeCall(to Ext 101)

lineGetCallInfo()

WINDOWS/TAPI

Success

Success

RequestID 123

LINE_REPLY 123 Success

LINE_CALLSTATE (Proceeding)

[Someone answers the phone]

LINE_CALLSTATE (Connected)

LINE_CALLINFO (xxxx)

Return LineCallInfo structure.


Typical Outgoing Call States

ID L E

B U S Y

D IS C O N N E C TE DID L E

ID L E

C O N N E C TE D

R IN G B A C K

ID L E

S P E C IA L IN F O

P R O C E E D IN G

D IA L IN G

D IA L TO N E


App to TAPI - InboundAPPLICATION

lineInitializeEx()

lineOpen()

[Wait for Call]

lineAnswer()

[Talk on the phone]

WINDOWS/TAPI

Success

Success

[Inbound Call Arrives]

LINE_APPNEWCALL

LINE_CALLSTATE (offering)

RequestID 123

LINE_REPLY 123 (Success)

LINE_CALLSTATE (Connected)


Typical Incoming Call States

ID L E

D IS C O N N E C TE DID L E

O N H O L D

ID L E D IS C O N N E C TE DID L E

C O N N E C TE D D IS C O N N E C TE DID L E

O F F E R IN G


Handles• With the potential for many lines to be open

and many calls to be in progress at the same time, Windows needs some way to track them

• A handle (call or line) is an arbitrary number that Window assigns, which you can use at a later time as a function parameter to refer to a specific call or line.


App to TAPI -HandlesAPPLICATION

lineInitializeEx()

lineOpen()

[Wait for Call]

lineAnswer(hCall)

[Talk on the phone]

WINDOWS/TAPI

Success

Success (return handle to line)

[Inbound Call Arrives]

LINE_APPNEWCALL(hCall)

LINE_CALLSTATE(hCall, OFFERING)

RequestID 123

LINE_REPLY 123 (Success)

LINE_CALLSTATE (hCall, Connected)


Event Driven Programming• A TAPI application will respond to events

(messages) that it receives from TAPI.– For example, whenever a call's state changes an

application receives the LINE_CALLSTATE message. A TAPI application responds by calling lineGetCallStatus() and checking the dwCallFeatures & dwCallFeatures2.

• These fields are a set of flags that tell the application what TAPI call functions can be used on the call now.

• Don't make assumptions about the underlying state machine.– Just because there are no calls active doesn't mean

you can call lineMakeCall() right now.


Shifting Perspective• For the most part, TAPI calls made by the

application to Windows are just passed along to the driver (the TSP) by TAPI.

• From the TSP’s perspective, Windows (TAPI) IS the application.

• The TSP sends messages to Windows, then Windows forwards them to the appropriate application(s).

• Not all API function calls are routed to the TSP, and not all messages are initiated by the TSP.


APPLICATION lineInitialize()

lineOpen()

lineMakeCall()

etc.

TSP Success Success Success Success

Success

DRVRequestID

LINE_REPLY

LINE_CALLSTATE

WINDOWS/TAPI TSPI_lineNegotiateTSPIVersion() TSPI_providerEnumDevices() TSPI_providerInit() TSPI_lineNegotiateTSPIVersion() (one per line) Success

TSPI_lineOpen () Success

TSPI_lineMakeCall() RequestID

LINE_REPLY

LINE_CALLSTATE

Applications, TAPI and TSPs


TAPI Elements• Application, TAPI and TSP interactions

involve the following elements:– Structures

• These are allocated and passed from Applications to TAPI and from TAPI to TSPs and back to communicate large amounts of information.

– Functions• Functions are calls from Apps to TAPI and TAPI to TSPs.

– Messages• Messages are "function calls" from a TSP to TAPI and

TAPI to Apps.– Constants

• These are enumeration values associated with function parameters, message parameters and structure fields.


Update Message SummaryMessage Structure Function

LineStatic

LINEDEVSTATE,(dwParam1 |=_CAPSCHANGE)

LINEDEVCAPS lineGetDevCaps

LineDynamic

LINE_DEVSTATE LINEDEVSTATUS lineGetLineDevStatus

AddressStatic

LINE_ADDRESSSTATE(dwParam2 |=_CAPSCHANGE)

LINEADDRESSCAPS lineGetAddressCaps

AddressDynamic

LINE_ADDRESSSTATE LINEADDRESSSTATUS lineGetAddressStatus

Call“Static”

LINE_CALLINFO LINECALLINFO lineGetCallInfo

CallDynamic

LINE_CALLSTATE LINECALLSTATUS lineGetCallStatus


Message Parameters• Line messages begin with "LINE_."

• Most LINE messages pass a dwInstanceData parameter. This is the same value passed in lineOpen(). Applications can use it to support OO techniques.

• Line Messages have three DWORD parameters, dwParam1, dwParam2 & dwParam3.

• Depending on the message, some of these parameters will contain data associated with the message.– Similar to Window Message's wParam and lParam.


Hold Call Example


Hold Call Example• Say you are writing a call control PIM

application and you want to support hold.– You could have a button labeled "Hold" and depending

on the ability of the line and address to support a hold capability, you could show or hide the button labeled "Hold."

– Whenever you are notified about a new call or a call state change then you could enable or disable your "Hold" button as appropriate.

• You should never assume that hold, or any other TAPI operation, is valid. You should always check the appropriate fields in the various capability and status structures before attempting to call any TAPI function.


Calling lineHold()• Putting the call on hold is as simple as the

application calling the lineHold() API when the call in in an appropriate call state (usually _CONNECTED.)

– We make sure that we get an async success indication (match up the dwRequestID we get back with the subsequent LINE_REPLY message).

– We make sure that the call really goes on hold, i.e., we get a LINE_CALLSTATE(_ONHOLD) message sometime after the LINE_REPLY.


Hold Call ExampleAPPLICATION

[Call Connected] lineHold()

WINDOWS/TAPI

TSPI_lineHold() RequestID

LINE_REPLY - Success

LINE_CALLSTATE (_ONHOLD)

TSP

DRVRequest ID

(Some time later)

LINE_REPLY - Success

(Some time later)

LINE_CALLSTATE(_ONHOLD)


Determine If We Can Ever Hold• However, to "do it right", the app needs to

determine if the address supports lineHold(), the API we use to put a call on hold.– Call lineGetAddressCaps() and look at the

LINEADDRESSCAPS structure that is returned:

• Check the dwCallFeatures field to see if it includes the LINECALLFEATURE_HOLD constant.

– If it does, then this indicates that we will be able to put calls, in an appropriate state, on hold on this address.

• Also, the dwCallStates field should include LINECALLSTATE_ONHOLD and the dwMaxOnHoldCalls field should be >= 1.

– If not then this indicates a bug in the TSP.


Determine If We Can Hold Now• We now need to determine if this specific call

can be put on hold right now, i.e., that the lineHold() API will not fail with a LINEERR_INVALIDCALLSTATE.– We call lineGetCallStatus() and examine the

dwCallFeatures of the LINECALLSTATUS structure for the LINECALLFEATURE_HOLD value.

• Don't confuse this with the similar field in the Address Caps. That is static, i.e., whether we will ever be able to put the call on hold, not whether we can put this call on hold right now.


Look at Other Aspects of Hold• Some APIs have side effects or peculiarities

that are communicated using fields of the various TAPI structures.

• For example, in the case of hold the LINEADDRESSCAPS has a field called dwAddrCapFlags which may have the LINEADDRCAPFLAGS_HOLDMAKESNEW bit set.– If this bit is set then this would indicate that when an

application puts a call on hold it should expect to see a new call appear, probably in a DIALTONE state.


TSP Support Of Hold• Now we move to the TSP's responsibilities.

• To support hold the TSP needs to: – Support the function and add an entry to its def file.

– Set fields in various static capability structures passed by TAPI functions to indicate:

• That the function is available

• Any call states related to its availablility.

• Any unique aspects of the behavior.

– Notify TAPI when the function can actually be used.

– Reflect any state changes that may result.


TSPI_lineHold() Function • Define the TSPI_lineHold() function in your

source code.– How you will actually hold the call when

TSPI_lineHold() is called is solution specific. For example you might:

• Send a TCP/IP request to a PBX telephony link.• Send a message to a phone on a serial connection.• Send an AT command to a modem.• Send a command to a phone board.• etc...

• Add an entry to the def file for TSPI_lineHold().– No ordinal needed as of TAPI 2.0.


TSP Hold Capabilities• In the LINEADDRESSCAPS structure for

TSPI_lineGetAddressCaps(), set:– dwCallFeatures |= LINECALLFEATURE_HOLD

– dwCallStates |= LINECALLSTATE_ONHOLD

– dwMaxNumOnHoldCalls >= 1

– Possibly dwAddrCapFlags | = LINEADDRCAPFLAGS_HOLDMAKESNEW

• In the LINECALLINFO structure returned by TSPI_lineGetCallInfo()– dwCallStates |= LINECALLSTATE_ONHOLD


TSP Hold Availability• When the call actually moves to a call state

where it can be placed on hold (typically LINECALLSTATE_CONNECTED.)

• In the LINECALLSTATUS structure returned by TSPI_lineGetCallStatus()– dwCallFeatures |= LINECALLFEATURE_HOLD


Hold State Change• A call can be put on hold by:

– TSPI_lineHold()

– Using the phone associated with the line to manually put a call on hold.

• A call can also appear initially in a hold state:– Queued

– Camped On

• No matter how, a TSP notifies TAPI and TAPI notifies the application by sending a LINE_CALLSTATE message with: – dwParam1 = LINECALLSTATE_ONHOLD


Hold - Summary• To summarize, at application startup:

– Call lineInitialize() to determine how many lines are in the system.

– Call lineGetDevCaps() on each line.

– From the returned LINEDEVCAPS structure, determine the number of addresses on the line from the dwNumAddresses field.

– Call lineGetAddressCaps() on each address.

– Examine the dwCallFeatures to determine if address supports holding calls.


Hold - Summary• Once the application is running, whenever we

get a LINE_CALLSTATE message, the app responds by:– Calling lineGetCallStatus().

– From the returned LINECALLSTATUS structure, examine the dwCallFeatures field to determine if we can use lineHold() right now.

• Finally, whenever we get a LINE_CALLSTATE message, update the UI to reflect the new state (in this case, on hold.)– This should also cause us to call lineGetCallStatus()

again and examine the call features to determine what we can do now on the call.


Querying Object States• The Hold example showed an application

making calls like lineGetAddressCaps() to determine the capabilities of the Address "object."

• Functions that query the static or dynamic object states are all synchronous.

• A TAPI app should not poll these objects to see when their state changes. Rather, when the state changes the TSP sends a message to TAPI and TAPI sends a message to the App(s).


Structures & Messages

Structures and messages in TAPI go hand and hand. Typically, when a TSP or TAPI changes the values in a structure they generate a message to notify interested Apps.


Structures• Structures are used to communicate large

amounts of data to TAPI and TSPs as well as to return data from TAPI and TSPs.

– Some information is also communicated via function parameters.

• The most important structures are associated with the Line, Address and Call.– Each of these objects has two principle structures:

• One for communicating relatively static capabilities and information.

• The other for communicating more dynamic information.


Line Structures• Static:

– LINEDEVCAPS

• Dynamic:– LINEDEVSTATUS


LINEDEVCAPS• Filled in by a TAPI and the TSP in response to

an app calling lineGetDevCaps().

• Important Fields include:– dwPermanentLineID

– dwLineNameSize/Offset

– dwNumAddresses

– dwDevCapFlags

– dwMaxNumActiveCalls

– dwLineStates


LINEDEVCAPS• If any of this "static" information changes,

TAPI will notify the app by sending:

– LINE_LINEDEVSTATE wheredwParam1 |= LINEDEVSTATE_CAPSCHANGE

• In addition to setting dwTotalSize, on return from TSPI_lineGetDevCaps() TAPI will OR the following values into dwLinesStates: – LINEDEVSTATE_OPEN

– LINEDEVSTATE_CLOSE

– LINEDEVSTATE_REINIT

– LINEDEVSTATE_TRANSLATECHANGE


LINEDEVSTATUS• Filled in by lineGetLineDevStatus().

• Important Fields include:– dwNumActiveCalls

– dwNumOnHoldCalls, dwNumHoldPendCalls.

– dwLineFeatures

– dwDevStatusFlags


LINEDEVSTATUS• Whenever any field(s) change, TAPI will notify

the app by sending:– LINE_LINEDEVSTATE with appropriate state value(s)

in dwParam1

• In addition to setting dwTotalSize, on return from TSPI_lineGetLineDevStatus() TAPI will also set:– dwNumOpens

– dwOpenMediaModes


Address Structures• Static:

– LINEADDRESSCAPS

• Dynamic:– LINEADDRESSSTATUS


LINEADDRESSCAPS• Filled in by lineGetAddressCaps().

• Important Fields include:– dwLineDeviceID (the owning line)– Address (variable)– dwAddressStates

– dwCallerIDFlags, dwCalledIDFlags, dwRedirectedFlags, dwRedirectingFlags, dwConnectedFlags

– dwCallInfoStates– dwCallStates– lots more...


LINEADDRESSCAPS• If any of this "static" information changes,

TAPI will notify the app by sending:– LINE_ADDRESSSTATE where

dwParam2 |= LINEADDRESSTATE_CAPSCHANGE

• In addition to setting dwTotalSize, on return from TSPI_lineGetAddressCaps() TAPI will:– OR into dwCallInfoStates the following values:

• LINECALLINFOSTATE_NUMOWNERINCR• LINECALLINFOSTATE_NUMOWNERDECR• LINECALLINFOSTATE_NUMMONITORS

– OR into dwCallStates the following additional value:• LINECALLSTATE_UNKNOWN


LINEADDRESSSTATUS• Filled in by lineGetAddressStatus().

• Important Fields include:– dwNumActiveCalls

– dwNumOnHoldCalls, dwNumHoldPendCalls.

– dwAddressFeatures

– dwForewardNumEntries

– Forward (variable list)


LINEADDRESSSTATUS• Whenever any field(s) change, TAPI will notify

the app by sending:– LINE_LINEADDRESSSTATE with dwParam1 set to

the address ID and the appropriate state value(s) in dwParam2

• TAPI only sets the dwTotalSize member on return from TSPI_lineGetAddressStatus().


Call Structures• Static:

– LINECALLINFO

• Dynamic: – LINECALLSTATUS


LINECALLINFO• Filled in by lineGetCallInfo().

• Important Fields include:– dwLineDeviceID, dwAddressID

– dwCallStates

– dwCallOrigin, dwCallReason

– dwAppSpecific

– CallerID, CalledID, ConnectedID, RedirectedID, RedirectingID


LINECALLINFO• Several of the LINECALLINFO fields relate to

TAPI 3rd Party Call Support.

• Call ID & Possibly Related Call ID– Each first party view of the same underlying call will

have the same dwCallID.

• Call Data– Applications associate information with a 3rd party call

through the Call Data field. TAPI set this data by calling TSPI_lineSetCallData() with the hdCall parameter set to any of the first party views of the call.


LINECALLINFO• Whenever any field(s) change, TAPI will notify

the app by sending:– LINE_CALLINFO with appropriate Call Info State(s) in

dwParam1.

• In addition to setting dwTotalSize, on return from TSPI_lineGetCallInfo() TAPI will set:– hLine– dwCallStates

• TAPI will OR in LINECALLSTATE_UNKNOWN– dwMonitorDigitModes, dwMonitorMediaModes– dwNumOwners, dwNumMonitors

– AppName, DisplayableAddress, CalledParty, Comment


LINECALLSTATUS• Filled in by lineGetCallStatus().

• Important Fields include:– dwCallState

– dwCallFeatures, dwCallFeatures2


LINECALLSTATUS• Whenever any field(s) change, TAPI will notify

the app by sending:– LINE_CALLSTATE with appropriate Call State in

dwParam1.

• In addition to setting dwTotalSize, on return from TSPI_lineGetCallStatus() TAPI will set:– dwCallPrivilege


Update Message SummaryMessage Structure Function

LineStatic

LINEDEVSTATE,(dwParam1 |=_CAPSCHANGE)

LINEDEVCAPS lineGetDevCaps

LineDynamic

LINE_DEVSTATE LINEDEVSTATUS lineGetLineDevStatus

AddressStatic

LINE_ADDRESSSTATE(dwParam2 |=_CAPSCHANGE)

LINEADDRESSCAPS lineGetAddressCaps

AddressDynamic

LINE_ADDRESSSTATE LINEADDRESSSTATUS lineGetAddressStatus

Call“Static”

LINE_CALLINFO LINECALLINFO lineGetCallInfo

CallDynamic

LINE_CALLSTATE LINECALLSTATUS lineGetCallStatus


Other Structures• LINECALLPARAMS

– Important structure used to pass data about a call to TAPI (and hence other TAPI apps.)

– Used in lineOpen() with LINEMAPPER device ID.

– Used in lineMakeCall() to indicate a specific address ID to dial the call on.

– Used in one step transfers to indicate consulting call destination address.

• LINEFORWARD, LINEFORWARDLIST

• Others specific to functions.


Returning Data in Structures• For functions that return large amounts of

data, apps allocate the memory in which data is returned. The app passes a pointer to this data and TAPI and the TSP fill it in.– Before the TSP is called, this memory will be initialized

and verified by TAPI.

– The structures contain a fixed sized piece followed by a variable length data portion.

– Variable length element are referenced by two fields:• dwXXXOffset: Offset of the data from start of structure.

– Note: If the structure is nested within another structure, then this offset is from the start of the outermost structure.

• dwXXXSize: Size of that data.


Variable Length Headers• Variable length data structures all start with:

– dwTotalSize• Set by the application.• Always at least the sizeof(structure).

• Usually larger to allow the TAPI and the TSP to tack on variable length data.

– dwNeededSize• Set by the TAPI.

• Total size needed for TAPI and the TSP to return all the variable length data.

– dwUsedSize• Set by TAPI.

• The size actually used. dwUsedSize will match dwNeededSize if all of the information was returned.


Messages• We've already seen the messages used to

notify applications of structure changes.

• We've also seen the LINE_REPLY sent when a function completes asyncronously.

• Other messages include:– LINE_APPNEWCALL

• Notify an app of a new call.

– LINE_CLOSE, LINE_CREATE & LINE_REMOVE• Notify an app of line changes.

– The rest of the messages are a result of TAPI functions that register the app for specific event notification.

• For example, lineMonitorDigits().


Functional Areas

The following section attempts to cover the various functions,

messages and structures as they relate to specific call control

functions.


Basic & Supplemental Services• TAPI documents talk about Basic Telephony

Services and Supplementary Telephony Services.

• Basic Services– A lot of these functions are supported by TAPI directly

(i.e., they don't map to a TSPI_ function and they aren't a TSP's responsibility.)

– Aside from initialization, shutdown and configuration related functions, a TSP only needs to support the ability to make, answer and hangup calls.

• There must be implemented by the TSP.


Supplemental Services• Supplemental Services

– These are optional for a TSP to implement.

– These functions all map to TSPI_ functions.

– Functional areas include:

• Advanced PBX type call control abilities including:

– Transfer, Conference, Park, Pickup, Forward, etc.

• Generating and monitoring Tones and DTMF digits.

• Agent Support in conjunction with a Proxy Request Handler Application.

• Phone Device Support.


Application Startup• Applications initialize TAPI in order to start

using TAPI line functions.

• The typical sequence is:– lineInitializeEx()

• Returns the total number of lines in the system.

– Loop calling lineGetDevCaps() for each line.

– Loop calling lineGetAddressCaps() for each address.

• In both cases, check various fields to determine which lines are appropriate to your application.

– Loop calling lineOpen() on each line you want to use.


lineOpen()• When an application calls lineOpen(), it needs

to specify several items:– The device ID of the line it is opening.– A location for TAPI to place the line handle.– The Privilege you are opening the line with.

• You can request to be an owner of new calls, a monitor, or that you only want to make outgoing calls.

• Even if you request to be an owner, TAPI may make some other app the owner. However, you can always use lineSetCallPrivilege() to take over ownership.

– An app that requests ownership of new calls also indicates the media mode(s) is will accept.

• TAPI has a fairly complex notion of how calls are handed off from application to application. Most of this relates to calls of different media modes arriving on the same line.


LINEMAPPER• An alternative to searching for a line that

meets specific requirements is to open the line passing the LINEMAPPER constant for the line device ID parameter in the lineOpen function.– The parameters desired on the line are specified in the

lpCallParams (LINECALLPARAMS) structure passed to lineOpen.

– The open can fail if there is no line that matches (LINEERR_LINEMAPPERFAILED.)

– If the Open succeed, the application can determine the device ID of the line by using the lineGetID() function passing the handle of the open line.


Configuring Lines• Applications can configure lines by calling the

lineConfigDialog() function.– This invokes a dialog in the TSP itself that allows the

TSP to support its own configuration.

– The TSP's UI DLL will be download to the client by TAPI 2.1 if neccassary.

• The TSP's UI function called is TUISPI_lineConfigDialog().

• Applications can save and restore a TSPs configuration infomation.– lineConfigDialogEdit()– lineGetDevConfig()– lineSetDevConfig()


Making and Answering Calls• Earlier we saw the basic sequence of

functions and messages used when making and answering a call in TAPI.

• Basic Call Control APIs include:– lineMakeCall()

– lineDial()

• Typically available on calls in a _DIALTONE mode.

– lineDrop()

• These may be all you get (Unimodem).


lineDial()• Applications generally create calls and dial

them with the lineMakeCall() API. However, there are situations where an application may have a need to dial a number on an existing call.– For example, when using the transfer or conference

APIs to dial a consulting call.

– Generally lineDial() is be available for _DIALTONE calls.

• An application determines if a call will currently allow lineDial() by examining:– LINECALLFEATURE_DIAL


Answering Calls• Call states when generally available:

– _ OFFERING and _ACCEPTED• Function

– lineAnswer()• ISDN or Advanced PBX

– lineAccept()– lineRedirect()– lineDrop()


Advanced Call Control• Most of the TAPI APIs and Messages are

related to the Supplemental Services. Most of these services relate to features commonly found on PBXs.

• PBX developers generally make these features available through their TSPs.

• An application should examine the line and address capability structures (LINEDEVCAPS & LINEADDRESSCAPS) to determine what functions are available.

• The capability structures also allow applications to determine, within certain limits, variations in a TSP's implementation.


Hold Call APIs• We already went through an example of using

the lineHold() functions.

• There are two other Hold related APIs besides lineHold.– lineUnhold()

• This is used to restore a held call to connected. If addition to usually requiring that the call being un-held be currently on hold, it also may require that there is currently no connected call on the address.

– lineSwapHold()

• This is used to swap a held call and a connected call. It may also be used to swap a camped/queued call with a connected call as these calls present in an _ONHOLD state.


Hold Call APIs1) lineMakeCall(x101)

[101 goes CONNECTED]

2) lineHold(101)[101 goes HELD][Maybe new DIALTONE call]

3) lineDial(x102) or lineMakeCall(x102)[102 goes CONNECTED]

4) lineSwapHold(101, 102)[101 goes CONNECTED][102 goes HELD]

5) lineDrop(101)[101 goes IDLE]

6) lineUnHold(102)[102 goes CONNECTED]

Ext 100

Ext 101 Ext 102

1, 5

2, 4, 6

3


Call Completion• Generally available on

LINECALLSTATE_BUSY calls.

• Functions:– lineCompleteCall()– lineUncompleteCall()

• Constants:– LINECALLCOMPLMODE_ constants

• LINECALLCOMPLMODE_CAMPON

• LINECALLCOMPLMODE_CALLBACK

• LINECALLCOMPLMODE_INTRUDE

• LINECALLCOMPLMODE_MESSAGE


Call Completion (1) lineMakeCall(x101)

[101 goes BUSY]

(2) lineCompleteCall(101, LINECALLCOMPLMODE_CALLBACK)[returns a Completion ID][101 goes IDLE]

[we wait for the call completion]

We could abandon waiting:

(3a) lineUncompleteCall(Completion ID)

If we wait:

[later on new call presents as OFFERING]

(3b) lineGetCallInfo()

[CallReason is _CALLCOMPLETION]

[CompletionID matches returned ID]

Ext 100

Ext 101

1

2, 3a

3b


Four Kinds of Transfer• Blind Transfer

• Consulting Transfer

• One-Step Consulting Transfer

• Transfer through Pickup– This is handled using linePickup().


Blind Transfer• The simplest way to transfer calls.

– Doesn't involve a consulting call.

• Used in PBX based TSPs.– May also support moving calls on and off hold point

and/or queues in TSPs that model hold point and/or queues as a line device.


Consulting Transfer• You use the lineSetupTransfer(), lineDial() &

lineCompleteTransfer() APIs to perform a consulting transfer.

• Support for this type of transfer is indicated in LINEADDRESSCAPS in:– dwTransferModes field

• LINETRANSFERMODE_TRANSFER

– dwCallFeatures2

• LINECALLFEATURE2_TRANSFERNORM


Consulting Transfer Ext 100

Ext 101 Ext 102

(1) lineMakeCall(x101)


(2) lineSetupTransfer(101)[101 goes ONHOLDPENDINGTRANSFER][returns new DIALTONE call]

(3) lineDial(x102) on new call[102 goes CONNECTED]

(4) lineCompleteTransfer(101, 102, LINETRANSFERMODE_TRANSFER)[101 & 102 both go IDLE][x101 & x102 should now be connected]

1

2, 4

3


One-Step Consulting Transfer• This is similar to the consulting transfer

except that we don't need to use the lineDial().

• Support for this type of transfer is indicated in LINEADDRESSCAPS in:– dwTransferModes field

• LINETRANSFERMODE_TRANSFER

– dwCallFeatures2

• LINECALLFEATURE2_TRANSFERNORM & LINECALLFEATURE2__ONESTEPTRANSFER.

• We use lpCallParams to make a one-step xfer:– We pass the number to dial and– LINECALLPARAMFLAGS_ONESTEPTRANSFER.


Five Kinds of Conference• Transfer resolved as a conference.

• One step transfer resolved as a conference.

• New conference call.

• Conference existing call.

• No hold conference.


xfer Resolved as a Conference• You use the lineSetupTransfer(), lineDial() &

lineCompleteTransfer() APIs to perform a conference.

• Support for this type of conference is indicated in LINEADDRESSCAPS in:– dwTransferModes field

• LINETRANSFERMODE_CONFERENCE

– dwCallFeatures2

• LINECALLFEATURE2_TRANSFERCONF


Transfer Conference(1) lineMakeCall(x101)

[101 gets CONNECTED]

(2) lineSetupTransfer(101)[101 goes ONHOLDPENDTRANSFER][returns new DIALTONE call]

(3) lineDial(x102) on new call[Wait for 102 to get CONNECTED]

(4) lineCompleteTransfer(101, 102, LINETRANSFERMODE_CONFERNCE)[returns CONNECTED conference call][101 & 102 go CONFERENCED]

Ext 100

Ext 101 Ext 102

1

2, 4

3


One Step xfer Conference• This is similar to the transfer conference

except that we don't need to use lineDial().

• Support for this type of conference is indicated in LINEADDRESSCAPS in:– dwTransferModes field

• LINETRANSFERMODE_CONFERENCE

– dwCallFeatures2

• LINECALLFEATURE2_TRANSFERCONF & LINECALLFEATURE2__ONESTEPTRANSFER.

• We use lpCallParams to make a one-step xfer:– We pass the number to dial (TargetAddress) and– LINECALLPARAMFLAGS_ONESTEPTRANSFER.


New Conference Call• Use the lineSetupConference(), lineDial(),

linePrepareAddToConference(), and lineAddToConference() APIs to create a new conference call.

• Support for this type of conference is indicated in LINEADDRESSCAPS in:

– dwCallFeatures

• LINECALLFEATURES_SETUPCONF

– dwAddrCapsFlags

• LINEADDRCAPFLAGS_SETUPCONFNULL


New Conference Call(1) lineSetupConference(x101)

[Returns new conference call in ONHOLDPENDCONF state][Returns new DIALTONE consult call]

(2) lineDial(x101) on new consult call[101 goes CONNECTED]

(3) lineAddToConference(ConfCall, 101)[101 gets CONFERENCED][Conf Call gets CONNECTED]

[We now have a one party Conference call]

[We do the following to add a second]

(4) linePrepareAddToConference(ConfCall)[Conf Call goes ONHOLDPENDCONF][Returns new DIALTONE consulting call]


(6) lineAddToConference(ConfCall, 102)[102 goes CONFERENCED][Conf Call goes CONNECTED]

Ext 100

Ext 101 Ext 102

2

1, 3, 4, 6

5


Conference Existing Call• Use the lineSetupConference(), lineDial(),

lineAddToConference() and possibly linePrepareAddToConference().


– dwCallFeatures

• LINECALLFEATURES_SETUPCONF

– dwAddrCapsFlags should not have LINEADDRCAPFLAGS_SETUPCONFNULL set.


Conference Existing Call(1) lineMakeCall(x101)


(2) lineSetupConference(101)[101 goes CONFERENCED][Returns new conf call in ONHOLDPENDCONF state][Returns new DIALTONE consult call]



[We could add more participants]

(5) linePrepareAddToConference(ConfCall)[Conf Call goes ONHOLDPENDCONF][Returns new DIALTONE consulting call]



Ext 100

Ext 101 Ext 102

1

2, 4, 5, 7

3

Ext 103

6


No Hold Conference• Uses the lineSetupConference() and/or

lineAddToConference().


– dwCallFeatures

• LINECALLFEATURES_SETUPCONF, _ADDTOCONF

– dwCallFeatures2

• LINECALLFEATURE2_NOHOLDCONFERENCE.


Removing Conference Party• Uses the lineRemoveFromConference() API.

• May be allowed on conference calls setup using the conference or transfer APIs.

• If after the party is removed, there are only two participants then the call MAY revert to a normal 2 party call– The participant call would go from CONFERENCED to

CONNECTED and the conference call would go IDLE.

• You can determine the state the participant call will go to after it is removed by examining the dwRemoveFromConfState field of the LINEADDRESSCAPS.


lineGetConfRelatedCalls()• This API is resolved completely by TAPI.

• It allows an application to determine the relationship between a conference call and its members.

• It can be called on any call in the conference or on the conference call itself.

• We will see later how a TSP tells TAPI the relationship between participant and conference calls created by the TSP (perhaps from a human user using their phone.)


linePickup()• Allows an application to pickup calls ringing at

another extension.

• There are several variants of how linePickup() may work.– You can pickup a call by specifying a number.

• LINEADDRFEATURE_PICKUPDIRECT

– You can pickup a call by specifying a group ID.• LINEADDRFEATURE_PICKUPGROUP

– You can pickup a call put on hold at another station.• LINEADDRFEATURE_PICKUPHELD

– You can pickup a call waiting call.• LINEADDRFEATURE_PICKUPWAITING


linePark() & lineUnpark()• linePark() can place a call in a park zone.

– There are two variants of how linePark() will work that are indicated in the dwParkModes field of the LINEADDRESSCAPS.

• You tell linePark() where to park the call.

– LINEPARKMODE_PARKDIRECT

• The TSP assigns an address where the call is parked and linePark() returns that address.

– LINEPARKMODE_PARKNONDIRECT

• lineUnpark() can retrieve a parked call.– You specify a number (orbit zone, etc.) from which to

retrieve the parked call.


lineForward()• This can be used at the line level to forward

ALL addresses on the line or the address level to forward just a single address on the line as well as to cancel forwarding.– Just what may be possible is determined by examining

the dwLineFeatures and the dwAddressFeatures.

• It may also be used to enable and disable do-not-disturb.

• When the forwarding status of an address or line changes, TSPs notify TAPI and TAPI notifies apps with the LINE_ADDRESSSTATE message.


Background Functions• A number of the TAPI functions kick off

background activities on a line, address or call.– Don't confuse these with the general async funcitons

(LINE_REPLY)

• These functions are generally async also.

– Events related to the activities generate messages.

– The activities will complete on their own (and will report this with an appropriate message) or can be canceled with the appropriate APIs.

• These functions (if supported by your TSP) will help you support IVR type applications.


Generating Digits and Tones• An application can cause a number of digits

to be dialed inband on the call.

– Call lineGenerateDigits() passing a string of digits to generate in the background.

• An application can also cause a number of DTMF tones to be played inband on the call.

– Call lineGenerateTones() passing a list of tones.

• LINE_GENERATE is sent when either generation is completed or canceled.

• Call lineGenerateDigits() with NULL digits string to cancel.

• Call lineGenerateTones() with a 0 tone mode to cancel.


Digit and Tone Monitoring• These allow the application to monitor for

inband digits and tones on a call.– Call lineMonitorDigits() to monitor digits.

• Whenever a digit is received or when monitoring is terminated, the app is sent LINE_MONITORDIGITS.

• An application can terminate digit monitoring by calling lineMonitorDigits with 0 DigitsMode.

– Call lineMonitorTones() to monitor tones.

• Whenever a tone is received or when monitoring is terminated the app is sent LINE_MONITORTONES.

• An application can terminate digit monitoring by calling lineMonitorTones() with a NULL ToneList.


Digit Gathering• This is like digit monitoring except that the

digits are built up in the background until a terminating state has been reached.– Call lineGatherDigits() to initiate digit gathering.

• Pass a count of digits requested and a buffer.• Terminating states include

– The number of requested digits read.– A specified digit received.– Timeout waiting for digits.

– When it hits a terminating state you will receive:• LINE_GATHERDIGITS

• Both digit gathering and digit monitoring can be on at the same time.


Media Control• TAPI Media Control allows you "program"

specific media actions such as playing a wave file, rewinding, etc. (think of voice mail) based on multi-step sequences of action based on received tones, digits, call states and media modes of the call.

• You set up the structures to define the events and actions then call lineSetMediaControl() to pass them to TAPI/TSP.

• Could be very useful in a client/server environment where you don't have the time to remotely react to a "next voice mail message" key press.


Extended Line Functions• TAPI provides mechanisms for TSP

developers to extend TAPI with proprietary extensions.– You would need these documented to be able to use

them.– APIs include

• lineNegotiateExtVersion()– Just like TAPI, a TSPs extensions could have multiple versions.

• lineDevSpecific() & lineDevSpecificFeature()– This is how you actually call the TSPs extensions.

– Messages include• LINE_DEVSPECIFIC, LINE_DEVSPECIFICFEATURE


Call Center Support• Modeling devices other then stations

– Call Queues– Route Points

• Predictive Dialing Support– Indicated by in the LINEADDRESSCAPS:

• dwAddrCapFlags has the LINEADDRCAPFLAGS_PREDICTIVEDIALER set.

• dwPredictiveAutoTransferStates lists the call states where the address can be setup to automatically transfer the call.

– To use, in lineMakeCall(), set in the Call Params:• LINECALLPARAMFLAGS_PREDICTIVEDIAL• dwPredictiveAutoTransferState


Supporting TSP Functions


Calling Functions• Applications call TAPI functions and TAPI in

turn calls TSP functions in two ways:– Synchronous– Asynchronous

• Most TAPI functions map one to one with TSPI functions. – lineMakeCall() calls TSPI_lineMakeCall(), lineDrop()

calls TSPI_lineDrop(), etc.• Some functions are handled only by TAPI.

– lineTranslateAddress(), lineGetConfRelatedCalls(), etc.• Some functions involve multiple TSP calls.

– lineInitializeEx(), etc.


Synchronous Functions• Initialization, shutdown, housekeeping and

information request functions are generally synchronous.

• Functions return Success (zero) or a negative TAPI error (LINEERR_...) value.

• Synchronous functions generally involve handling variable length structures.


TSP Code for Tacking On Datavoid TackOnData(void* pData, LPCWSTR pStr, DWORD* pSize){ // We could use any struct with a variable header LINEDEVCAPS* pDH = (LINEDEVCAPS *)pData; int cbStr = (strlen(pStr) + 1) * 2; if (cbStr > 2) { pDH->dwNeededSize += cbStr; // Update the needed size // Do we have space to add this data? if (pDH->dwTotalSize >= pDH->dwUsedSize + cbStr) { memcpy((char *)pDH + pDH->dwUsedSize, pWStr, cbStr); DWORD* pOffset = pSize + 1; *pSize = cbStr; *pOffset = pDH->dwUsedSize; pDH->dwUsedSize += cbStr; } }}

// Usage example of tacking on the dataTackOnData(lpCallInfo, L"3047", &lpCallInfo->dwCalledIDSize);


Asynchronous Functions• Most TSP functions complete asyncronously.

– These functions return:

• An immediate error (LINEERR_xxx, i.e., a negative number) or

• A DRVRequestID (i.e., a DWORD). This is used to associate a pending function with async. returns.

– Async functions will NEVER return synchronously with success (zero.)

– The mechanism for receiving LINE_REPLYs as well as messages depends on the notification method selected in LineInitializeEx().


Completing Async• For TSPs, even if you can do all your

processing in the synchronous portion of the call, you can't return zero (success.)

• However, you don't actually need to complete it asynchronously.– Just call the completion function before you return, i.e.,

... (*lpfnCompletionProc)(dwRequestID, 0);

return dwRequestID;

}

– TAPI will take care of delivering the LINE_REPLY to applications after the synchronous return from the function.


TSP Initialization/Shutdown• When the first App calls lineInitialize()

– TAPI calls the TSP's:• TSPI_lineNegotiateTSPIVersion()

– Negotiates overall API version (the line device ID is set to INITIALIZE_NEGOTIATION.)

• TSPI_providerEnumDevices()– Determine how many devices the TSP supports.

– Provide a callback location to notify TAPI of new or removed lines. The same passed in TSPI_lineOpen.

• TSPI_providerInit()

– To get the TSP to create the lines to support capability queries and line open requests.

• When the last App calls lineShutdown()– TAPI calls TSPI_providerShutdown().


Line Creation and Removal• A TSP can create lines statically at init time:

– A TSP tells TAPI how many static lines (and phones) it has in response to TSPI_providerEnumDevices().

– These lines are assigned consecutive Device IDs starting from the dwLineDeviceIDBase parameter passed to TSPI_providerInit().

• A TSP can creates lines dynamically by sending LINE_CREATE messages to TAPI.– A TSP that supports adding lines will need to be able

to handle non-consecutive device IDs internally.

• A TSP can permanently remove a line by sending a LINE_REMOVE message to TAPI.


Line Handles• TAPI and TSP maintain separate handles to

the same underlying line.

• TSPI_lineOpen() allows TAPI and the TSP to exchange line handles– TSPI_lineOpen() contains a HTAPILINE parameter

which is TAPI's handle for this line.

– TSPI_lineOpen() also contains a pointer to a HDRVLINE which is where the TSP puts its handle.

• The TSP uses TAPI's HTAPILINE handle when sending messages to TAPI.

• TAPI uses the TSP’s HDRVLINE handle when calling TSPI functions.


Closing Lines• Lines will be closed when the last application

to have the line open calls lineClose().

• In response, TAPI will call TSPI_lineClose().

• A TSP can force its line to be closed by sending a LINE_CLOSE message to TAPI. In response TAPI will:– Send all the applications which have the line open a

LINE_CLOSE message.

– Call TSPI_lineClose().


Call Handles• Calls can be created by a TSP in response to

a TSPI line or address function or as a result of an external event by the TSP.

• Like line handles, TAPI and TSP maintain separate handles for the same underlying call.

• TSPI functions that can create calls allow TAPI and the TSP to exchange call handles:– The function will contain a htCall (HTAPICALL)

parameter which is TAPI's handle for the call.

– The function also contains a lphdCall (HDRVCALL pointer) which is where the TSP puts its call handle.


Call Creating APIs• The following APIs can potentially create a

new call handle.– TSPI_lineMakeCall()– TSPI_lineCompleteTransfer()– TSPI_lineForward()– TSPI_linePickup()– TSPI_linePrepareAddToConference()– TSPI_lineSetupConference()– TSPI_lineSetupTransfer()– TSPI_lineUnpark()


TSP Created Calls• TSPs can create calls asynchronously in

response to external events such as a phone physically going off hook or an incoming call.

• TSP notifies TAPI of the new call by sending a LINE_NEWCALL message to TAPI.

• The TSP exchanges call handles with TAPI by:

– Passing the HDRVCALL handle in dwParam1 of the LINE_NEWCALL message.

– Passing a pointer to a HTAPICALL where TAPI will deposit its call handle on return from sending the LINE_NEWCALL message.


TSP Created Conf. Calls• If a TSP creates a conference call in response

to an external action (i.e., not a TAPI call) then it needs a way to tell TAPI which call is the conference parent– When the TSP sends the LINECALLSTATE message

with a state of LINECALLSTATE_CONFERENCED, it sets the dwParam2 to the HTAPICALL of the parent.

– Make sure that you have notified TAPI about the new parent conference call first through a LINE_NEWCALL when you send the LINECALLSTATE message for the children.


Externally Generated Numbers• How does a TSP indicate the number dialed to

applications when, for example, the call is dialed from a phone associated with the line?

• There are several options that MS recommends:– Set the DisplayableAddress, CalledParty, or

Comment members in the LINECALLINFO structure.

– Normally TAPI sets these fields on return from TSPI_lineGetCallInfo(), but it won't for TSP generated calls.

– Set the CalledID member of the LINECALLINFO structure.


TAPI Handle TSPHandle

Line HTAPILINE HDRVLINE

Address HTAPILINE +Address ID

HDRVLINE+ Address ID

Call HTAPICALL HDRVCALL

Handle Summary


Example - Loss of PBX Link• Example, how could a TSP handle losing a

link to its PBX? There are three possible ways this could be handled.

• Close all lines– When the link is lost, send TAPI a LINE_CLOSE for

each line.

– TAPI will respond by calling TSPI_lineClose().

– Respond to future TSPI_lineOpen() requests with an appropriate LINEERR_ value.

– When the link is restored, accept TSPI_lineOpen() requests.


Example - Loss of PBX Link• Remove all lines

– Send LINE_REMOVE messages for each line.– TAPI calls TSPI_lineCloseCall() for all the calls.– TAPI will then call TSPI_lineClose() for each line.– On link restored, send a LINE_CREATE for each line.

• Mark all lines out of service– When the link is lost, idle all the calls.

– Send TAPI a LINE_LINEDEVSTATE message with dwParam1=LINEDEVSTATE_OUTOFSERVICE.

– When the link is reestablished notify TAPI with a LINE_LINEDEVSTATE message with dwParam1=LINEDEVSTATE_INSERVICE.


Messages• Messages are how a TSP "calls" TAPI.

– A TSP is passed a callback function address for it to call when it wants to deliver a message to TAPI.

• For Line Devices, TSPI_enumDevices() & TSPI_lineOpen().

• For Phone Devices, TSPI_enumDevices() & TSPI_phoneOpen().

– Some messages prompt TAPI to call a function in the TSP, i.e., sending LINE_CREATE causes TAPI to call TSPI_lineCreate()

– Line callbacks take the form:(*lpfnEventProc)(htLine, htCall, dwMsg, dwParam1, dwParam2, dwParam3)


The TUISPI DLL


TUISPI DLL• Starting with TAPI 2.0, TSPs are divided into

two portions, a DLL file (with a TSP extension) and a TUISPI DLL file.

• The TUISPI DLL is needed so that when a remote client calls UI generating APIs, TAPI can download the UI portion of the TSP.

• TUISPI functions have the same name as the associated TSPI functions but with TUISPI_.

• These are the TSP functions that call TUISPI:

– TSPI_providerConfig(), TSPI_providerInstall(), TSPI_providerRemove(), TSPI_lineConfigDialog(), TSPI_lineConfigDialogEdit(), TSPI_phoneConfigDialog().


TUISPI DLL Example• An application calls lineConfigDialog()

• TAPI calls TSPI_providerUIIdentify() in the TSP to determine the name of the TUISPI DLL.

• TAPI downloads the TUISPI DLL to the client if the client is remote.

• TAPI calls TUISPI_lineConfigDialog().

• Using a function pointer passed in the TUISPI_ function, the TUISPI DLL calls back to the TSP to request data and to update changes.

• TSPI_providerGetGenericDialogData() is called in the TSP as a result of the call back.


TUISPI DLL Diagram

TSP

TAPITUISPIDLL

RemoteTSP

TAPITUISPI

DLL

App

SERVER | CLIENT

|

|

|

|

|

|

|

|


Proxy Request HandlersACD Support


Proxy Request Handlers• Currently can be used to support internal and

external ACDs.

• May expand in the future, but for now Proxy Request Handlers only relate to ACD.

• Whenever a TAPI application calls agent related functions (lineGetAgentCaps(), etc.), these are passed to a server based application that has registered by using lineInitializeEx() options.

• This Server based app could communicate with a PBX to support built in Agent Support.


Proxy Handler DiagramPBX

w/ACD

TSP

TAPI

Application

Proxy RequestHandler


Proxy Request Handlers• When an application makes a request the

following routing occurs.– Request goes from the App to TAPI.

– TAPI sends the request to the proxy request handler with the LINE_PROXYREQUEST message.

– The agent app responds by calling the TAPI function lineProxyResponse() passing any data.

• The agent app may need to send a request to PBX to complete the request. It can talk directly to the PBX or use the TSP by sending a lineDevSpecific().

– When the agent app detects an event (directly or via the TSP) it calls lineProxyMessage() to generates a LINE_AGENTSTATUS message to the app.


TAPI 2.1 Client Management


TAPI Client Management DLLs• TAPI 2.1 introduced a new type of TAPI

program called a Client Management DLL.– TCM DLLs provide a mechanism to "hook" some of the

TAPI requests made by clients.

– These DLLs can pass on, reject or modify the parameters of the TAPI function calls.

• DLLs are not called for applications on the server.

– They are installed on the server using TCMSETUP.

– Any number can be installed. TAPI will sequentially call the DLLs in installed order.

• TCM DLLs can be used to support enhanced security, LCR, etc.


Client Management APIs• TCM APIs have a number of features.

– TCM APIs all start with TAPICLIENT_

– When a client attaches, a TCM DLL generates a handle of type MANAGEMENTCLIENT to track the client.

– Most of the TCM APIs correspond to a TAPI function.

• lineOpen() calls TAPICLIENT_LineOpen(),

• lineMakeCall() calls TAPICLIENT_LineMakeCall(),

• etc.


Client Management APIs• There are four TCM functions which aren't tied

to a specific TAPI function.– Two notify the TCM DLL when a client starts and ends.

• TAPICLIENT_ClientInitialize()

– This function provides information about a newly attaching client. It returns a MANAGEMENTCLIENT handle.

• TAPICLIENT_ClientShutdown

– Two notify the TCM DLL when its loaded and unloaded.

• TAPICLIENT_Load()

– This is called after TAPI has loaded the DLL.

• TAPICLIENT_Free()


TCM DLL DiagramSERVERMachine

TAPIApplication

TAPI32

TAPISRV

REMOTESPServiceProvider

TAPISRV

ClientManagement

DLLs

CLIENTMachine



Advanced Topics

Tips

Modeling

Development

Debugging


Tips before you code• Implementing a TSP is a bear but...

– Don’t do more then you have to.

– Take the time to know your switch or hardware capabilities well. Understand all the nuances of switch behavior, recalls, forward capabilities, etc.

– For a switch, usually the biggest job is supporting some kind of call control API on the switch and making it accessible to your TSP.

– Use MSDN. Read the TAPI docs. There's a lot of really good info buried in them.

• Note: Current docs are inconsistent and at times the advice conflicts with current MS recommendations.


Modeling your Environment• Will you support one line or many?

– Will you support third party CC with TAPI 2.1?

• Will you support one address per line or more?– TAPI 2.1 associates client permissions with lines.

• Current docs talk about supporting third party CC through many addresses on a single line but this is no longer recommended.

– MS says model features like speed dial keys that show an address status as a non-dialable address.

• May not be needed if primary interest is 3rd party apps.

– Multiple calls on a line don't mean multiple addresses.


Modeling your Environment• Will you be modeling trunks and queues as

well as extension?– If you do, you may be able to support applications like:

• Off-switch ACD

• Predictive Dialer

• etc.

– If you just model extensions, you can still support applications like:

• PIMs via TAPI 2.1.

• Operator.

• Call accounting.

• etc.


Implementation Strategies• Start by laying out the TSPs infrastructure.

– Provide entry point for all functions or at least all the functions you know you want to support.

– Create objects with member functions for the principle TAPI objects and connect to entry point functions.

– Create functions wrappers for sending messages to TAPI.

• Get all event notification and information APIs working BEFORE you handle functional APIs.

– You want to minimize differences in how you handle events generated externally versus the result of APIs.


Things to Discuss• Don’t simulate capabilities that your HW doesn’t have.

• Complete async LINE_REPLYs before reporting events. – At least for TSPI_lineDrop() and the call creation APIs.

• Use the same underlying logic to generate the dwFeatures fields for the various object structures as you do to check state validity at function entry.

• Present camped and queued calls as LINECALLSTATE_ONHOLD.

• Handle bridged calls.– LINEADDRESSSHARING, LINEOFFERINGMODE_INACTIVE,

LINECONNECTMODE_INACTIVE

• Presenting calls already on the device at TSPI_lineOpen().


External Utilities Strings• Where TAPI system utilities get their

information:

– The String shown in the Telephony Control Panel comes from FileDescription field of the TSP’s Version Resource.

– The strings shown in the TAPI 2.1's TCMapp utility are the LineName, SwitchInfo & ProviderInfo fields of the LINEDEVCAPS structure.


Developing a TSP with MFC• Currently no MFC support specifically for

TAPI app or TSP developers.

• Still well worth using for its CString, CObject derivation, collections, dialogs, etc.

• To get at resources in your TSP you need to throw this MFC "voodoo" in your code:TSPI_lineHold(HTLINE htLine){ AFX_MANAGE_STATE(GetModuleState()) ...


General C++ Ideas For TSPs• Four main classes:

CProvider CLine CAddress CCall

• Start by writing a wrapper module that converts your exported TSPI_xxx functions to member functions calls in the appropriate classes.

• This is also a good place to throw in debug output statements to track function entry and exit as well as parameters passed and return values.


More C++ Ideas for TSPs• Make your htLine and htCall your Cline and CCall

object pointers respectively. Then when you are called, you can just cast them to the correct type of object and call the underlying member function.

• Make your CProvider globally accessible.

• In your CProvider, maintain an array or collection (if you support dynamic line creation) of CLines.

• In your CLines, maintain an array of your CAddresses (if you support multiple addresses.)

• Finally, in your CAddresses maintain a collection of CCalls on the CAddress.


Putting this all togetherLONG TSPI_lineDrop(DRV_REQUESTID dwRequestID, HTCALL htCall){

TSPIDebugEntry("TSPI_lineDrop");AFX_MANAGE_STATE(AfxGetStaticModuleState());CCall* pCall = (CCall*)htCall;ASSERT(pCall->IsKindOf(RUNTIME_CLASS(CCall)));LONG lResult = pCall->Hold(dwRequestID);return lResult;

}

LONG CCall::Hold(DRV_REQUESTID dwRequestID){

// For example, send a message to a CTI Serverm_pCTIProtocolSocket->Write(m_CTICallID, MSGTYPE_HOLD);

// Complete async as sync(*g_Provider->m_lpfnCompletionProc)(dwRequestID, 0);return (LONG)dwRequestID;

}


Getting debug output• You can generate debug output from your

TSP as well as TAPI itself. To view this output you have two options:

– Run under a debugger.– Run an external debug capture utility.

• I wrote a simple NT debug capture utility called DBWin32 which you can download from my Web Page at:

– http://ourworld.compuserve.com/homepages/schenck/

• To output debug information from your TSP use MFC’s Trace() or OutputDebugString() generously.


TAPI Debug Output• To get TAPI to generate debug information:

– You need to run with the debug versions of the TAPI components rather then the standard ones.

– Enable TAPI debug output by creating and changing DWORD values found under

• \HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony

– Values range from from 0 (no debug output) to 4 (maximum debug output).

– Value names follow the convention “<ModuleName>DebugLevel”, e.g.,

• “Tapi32DebugLevel”, • “TapisrvDebugLevel”, • etc.


Debugging TAPISRV • You can run TAPISRV under a debugger and set

breakpoints in your TSP, UI DLL and TCM DLLs.

– First, make sure TAPISRV is not running. To check, go to Services under the control panel.

– Change the “ImagePath” value under \HKLM\SYSTEM\CurrentControlSet\Services\Tapisrv from “c:\winnt\system32\tapisrv.exe” to “c:\msdev\bin\msdev.exe c:\winnt\system32\tapisrv.exe” (changing relevent path and debugger names as appropriate).

– Next time TAPISRV starts, the debugger will load.

– You can also attach to TAPISRV, if it is already running.


Summing Up


Problems with TAPI• Complexity

– One size fits all means endless flags and settings:

• Tough for TSP developers to set and track.

• Also tough for applications developers as they have to make sense of the mass of capabilities exported by TSPs.

– Combination of media oriented API directed at modem and voice board based TSPs mixed in with call control APIs aimed at PBX based TSPs tends to make TAPI somewhat massive.

– The dream of auto-magically adapting to the underlying capabilities of a line by examining the capabilities is impossible to guarantee without testing.


The future of TAPI• According to MS, the next version of TAPI will

support remote media streams.– This would allow a client using REMOTE.TSP to get

access to the wave or comm device associated with a line.

• Support for Internet Telephony– Will we see a line or address capability that relates to

voice-on-the-net type lines?

– NetMeeting Integration at some level.

july 9, 1997copyright 1997, grant schenck software1 tapi 2.0/2.1 genoa technology san jose,...

Documents