1.84k likes | 2.66k Vues
TAPI 2.0/2.1. Genoa Technology San Jose, California July 9th, 1997. Grant Schenck, Grant Schenck Software Schenck@Compuserve.com. Introductions. Genoa Technology Grant Schenck Attendees Name, Company TAPI and Other CTI Experience App and/or TSP development? TAPI Versions?
E N D
TAPI 2.0/2.1 Genoa Technology San Jose, California July 9th, 1997 Grant Schenck,Grant Schenck SoftwareSchenck@Compuserve.com Copyright 1997, Grant Schenck Software
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? Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
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 Copyright 1997, Grant Schenck Software
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 Copyright 1997, Grant Schenck Software
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 Copyright 1997, Grant Schenck Software
Introduction Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
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! Copyright 1997, Grant Schenck Software
TAPI Versions Copyright 1997, Grant Schenck Software
TAPI Architecture (2.0) Diagram Copyright (c) 1997, Microsoft Corporation Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
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.) Copyright 1997, Grant Schenck Software
TSP Physical Models • PBX CTI Link • Modem Based • Phone Based • Voice Board Based Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
TAPI 2.1 Architecture Diagram Copyright (c) 1997, Microsoft Corporation Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
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 Copyright 1997, Grant Schenck Software
TAPI Resources • 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. Copyright 1997, Grant Schenck Software
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 Copyright 1997, Grant Schenck Software
Basic Concept Copyright 1997, Grant Schenck Software
The Big Picture Application 1 Application n TAPI TSP 1 TSP m Copyright 1997, Grant Schenck Software
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(). Copyright 1997, Grant Schenck Software
TAPI Object Hierarchy Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
Getting Oriented Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
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 back- ground. Windows lets you know at a later time if the function executed successfully (Request ID and LINE_REPLY.) Copyright 1997, Grant Schenck Software
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) Copyright 1997, Grant Schenck Software
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!) Copyright 1997, Grant Schenck Software
APPLICATION 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. App to TAPI - Outbound Copyright 1997, Grant Schenck Software
Typical Outgoing Call States Copyright 1997, Grant Schenck Software
APPLICATION 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) App to TAPI - Inbound Copyright 1997, Grant Schenck Software
Typical Incoming Call States Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
APPLICATION 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) App to TAPI -Handles Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software
APPLICATION lineInitialize() lineOpen() lineMakeCall() etc. TSP Success Success Success Success Success DRVRequestID LINE_REPLY LINE_CALLSTATE Applications, TAPI and TSPs WINDOWS/TAPI • TSPI_lineNegotiateTSPIVersion() • TSPI_providerEnumDevices() • TSPI_providerInit() • TSPI_lineNegotiateTSPIVersion() (one per line) • Success • TSPI_lineOpen () • Success • TSPI_lineMakeCall() • RequestID • LINE_REPLY • LINE_CALLSTATE Copyright 1997, Grant Schenck Software
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. Copyright 1997, Grant Schenck Software