July 9, 1997Copyright 1997, Grant Schenck Software1 TAPI 2.0/2.1 Genoa Technology San Jose, California July 9th, 1997 Grant Schenck, Grant Schenck Software.

July 9, 1997Copyright 1997, Grant Schenck Software2 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?

July 9, 1997Copyright 1997, Grant Schenck Software3 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.

July 9, 1997Copyright 1997, Grant Schenck Software4 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

July 9, 1997Copyright 1997, Grant Schenck Software5 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

July 9, 1997Copyright 1997, Grant Schenck Software6 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

July 9, 1997Copyright 1997, Grant Schenck Software8 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.

July 9, 1997Copyright 1997, Grant Schenck Software9 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.

July 9, 1997Copyright 1997, Grant Schenck Software10 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.

July 9, 1997Copyright 1997, Grant Schenck Software11 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.

July 9, 1997Copyright 1997, Grant Schenck Software12 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!

July 9, 1997Copyright 1997, Grant Schenck Software15 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.

July 9, 1997Copyright 1997, Grant Schenck Software16 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.)

July 9, 1997Copyright 1997, Grant Schenck Software18 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.

July 9, 1997Copyright 1997, Grant Schenck Software20 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.

July 9, 1997Copyright 1997, Grant Schenck Software21 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

July 9, 1997Copyright 1997, Grant Schenck Software22 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

July 9, 1997Copyright 1997, Grant Schenck Software23 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

July 9, 1997Copyright 1997, Grant Schenck Software26 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().

July 9, 1997Copyright 1997, Grant Schenck Software28 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.

July 9, 1997Copyright 1997, Grant Schenck Software29 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.

July 9, 1997Copyright 1997, Grant Schenck Software30 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.

July 9, 1997Copyright 1997, Grant Schenck Software31 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.

July 9, 1997Copyright 1997, Grant Schenck Software32 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.

July 9, 1997Copyright 1997, Grant Schenck Software33 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.

July 9, 1997Copyright 1997, Grant Schenck Software34 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.

July 9, 1997Copyright 1997, Grant Schenck Software35 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.

July 9, 1997Copyright 1997, Grant Schenck Software37 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.

July 9, 1997Copyright 1997, Grant Schenck Software38 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.)

July 9, 1997Copyright 1997, Grant Schenck Software39 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)

July 9, 1997Copyright 1997, Grant Schenck Software40 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!)

July 9, 1997Copyright 1997, Grant Schenck Software41 App to TAPI - Outbound APPLICATION  lineInitializeEx()  lineOpen()  lineMakeCall(to Ext 101)  lineGetCallInfo() WINDOWS/TAPI  Success  RequestID 123  LINE_REPLY 123 Success  LINE_CALLSTATE (Proceeding) [Someone answers the phone]  LINE_CALLSTATE (Connected)  LINE_CALLINFO (xxxx)  Return LineCallInfo structure.

July 9, 1997Copyright 1997, Grant Schenck Software43 App to TAPI - Inbound APPLICATION  lineInitializeEx()  lineOpen() [Wait for Call]  lineAnswer() [Talk on the phone] WINDOWS/TAPI  Success [Inbound Call Arrives]  LINE_APPNEWCALL  LINE_CALLSTATE (offering)  RequestID 123  LINE_REPLY 123 (Success)  LINE_CALLSTATE (Connected)

July 9, 1997Copyright 1997, Grant Schenck Software45 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.

July 9, 1997Copyright 1997, Grant Schenck Software46 App to TAPI -Handles 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)

July 9, 1997Copyright 1997, Grant Schenck Software47 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.

July 9, 1997Copyright 1997, Grant Schenck Software48 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.

July 9, 1997Copyright 1997, Grant Schenck Software49 APPLICATION  lineInitialize()  lineOpen()  lineMakeCall()  etc. TSP  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

July 9, 1997Copyright 1997, Grant Schenck Software50 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.

July 9, 1997Copyright 1997, Grant Schenck Software52 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.

July 9, 1997Copyright 1997, Grant Schenck Software54 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.

July 9, 1997Copyright 1997, Grant Schenck Software55 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.

July 9, 1997Copyright 1997, Grant Schenck Software56 Hold Call Example APPLICATION [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)

July 9, 1997Copyright 1997, Grant Schenck Software57 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.

July 9, 1997Copyright 1997, Grant Schenck Software58 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.

July 9, 1997Copyright 1997, Grant Schenck Software59 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.

July 9, 1997Copyright 1997, Grant Schenck Software60 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.

July 9, 1997Copyright 1997, Grant Schenck Software61 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.

July 9, 1997Copyright 1997, Grant Schenck Software62 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

July 9, 1997Copyright 1997, Grant Schenck Software63 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

July 9, 1997Copyright 1997, Grant Schenck Software64 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

July 9, 1997Copyright 1997, Grant Schenck Software65 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.

July 9, 1997Copyright 1997, Grant Schenck Software66 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.

July 9, 1997Copyright 1997, Grant Schenck Software67 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).

July 9, 1997Copyright 1997, Grant Schenck Software68 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.

July 9, 1997Copyright 1997, Grant Schenck Software69 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.

July 9, 1997Copyright 1997, Grant Schenck Software71 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

July 9, 1997Copyright 1997, Grant Schenck Software72 LINEDEVCAPS If any of this "static" information changes, TAPI will notify the app by sending: –LINE_LINEDEVSTATE where dwParam1 |= 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

July 9, 1997Copyright 1997, Grant Schenck Software73 LINEDEVSTATUS Filled in by lineGetLineDevStatus(). Important Fields include: –dwNumActiveCalls –dwNumOnHoldCalls, dwNumHoldPendCalls. –dwLineFeatures –dwDevStatusFlags

July 9, 1997Copyright 1997, Grant Schenck Software74 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

July 9, 1997Copyright 1997, Grant Schenck Software76 LINEADDRESSCAPS Filled in by lineGetAddressCaps(). Important Fields include: –dwLineDeviceID (the owning line) –Address (variable) –dwAddressStates –dwCallerIDFlags, dwCalledIDFlags, dwRedirectedFlags, dwRedirectingFlags, dwConnectedFlags –dwCallInfoStates –dwCallStates –lots more...

July 9, 1997Copyright 1997, Grant Schenck Software77 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

July 9, 1997Copyright 1997, Grant Schenck Software78 LINEADDRESSSTATUS Filled in by lineGetAddressStatus(). Important Fields include: –dwNumActiveCalls –dwNumOnHoldCalls, dwNumHoldPendCalls. –dwAddressFeatures –dwForewardNumEntries –Forward (variable list)

July 9, 1997Copyright 1997, Grant Schenck Software79 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().

July 9, 1997Copyright 1997, Grant Schenck Software81 LINECALLINFO Filled in by lineGetCallInfo(). Important Fields include: –dwLineDeviceID, dwAddressID –dwCallStates –dwCallOrigin, dwCallReason –dwAppSpecific –CallerID, CalledID, ConnectedID, RedirectedID, RedirectingID

July 9, 1997Copyright 1997, Grant Schenck Software82 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.

July 9, 1997Copyright 1997, Grant Schenck Software83 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

July 9, 1997Copyright 1997, Grant Schenck Software85 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

July 9, 1997Copyright 1997, Grant Schenck Software87 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.

July 9, 1997Copyright 1997, Grant Schenck Software88 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.

July 9, 1997Copyright 1997, Grant Schenck Software89 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.

July 9, 1997Copyright 1997, Grant Schenck Software90 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().

July 9, 1997Copyright 1997, Grant Schenck Software91 Functional Areas The following section attempts to cover the various functions, messages and structures as they relate to specific call control functions.

July 9, 1997Copyright 1997, Grant Schenck Software92 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.

July 9, 1997Copyright 1997, Grant Schenck Software93 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.

July 9, 1997Copyright 1997, Grant Schenck Software94 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.

July 9, 1997Copyright 1997, Grant Schenck Software95 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.

July 9, 1997Copyright 1997, Grant Schenck Software96 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.

July 9, 1997Copyright 1997, Grant Schenck Software97 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()

July 9, 1997Copyright 1997, Grant Schenck Software98 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).

July 9, 1997Copyright 1997, Grant Schenck Software99 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

July 9, 1997Copyright 1997, Grant Schenck Software100 Answering Calls Call states when generally available: –_ OFFERING and _ACCEPTED Function –lineAnswer() ISDN or Advanced PBX –lineAccept() –lineRedirect() –lineDrop()

July 9, 1997Copyright 1997, Grant Schenck Software101 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.

July 9, 1997Copyright 1997, Grant Schenck Software102 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.

July 9, 1997Copyright 1997, Grant Schenck Software103 Hold Call APIs 1)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 101Ext 102 1, 5 2, 4, 6 3

July 9, 1997Copyright 1997, Grant Schenck Software104 Call Completion Generally available on LINECALLSTATE_BUSY calls. Functions: –lineCompleteCall() –lineUncompleteCall() Constants: –LINECALLCOMPLMODE_ constants LINECALLCOMPLMODE_CAMPON LINECALLCOMPLMODE_CALLBACK LINECALLCOMPLMODE_INTRUDE LINECALLCOMPLMODE_MESSAGE

July 9, 1997Copyright 1997, Grant Schenck Software105 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

July 9, 1997Copyright 1997, Grant Schenck Software106 Four Kinds of Transfer Blind Transfer Consulting Transfer One-Step Consulting Transfer Transfer through Pickup –This is handled using linePickup().

July 9, 1997Copyright 1997, Grant Schenck Software107 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.

July 9, 1997Copyright 1997, Grant Schenck Software108 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

July 9, 1997Copyright 1997, Grant Schenck Software109 Consulting Transfer Ext 100 Ext 101Ext 102 (1)lineMakeCall(x101) [101 goes CONNECTED] (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

July 9, 1997Copyright 1997, Grant Schenck Software110 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.

July 9, 1997Copyright 1997, Grant Schenck Software111 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.

July 9, 1997Copyright 1997, Grant Schenck Software112 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

July 9, 1997Copyright 1997, Grant Schenck Software113 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 101Ext 102 1 2, 4 3

July 9, 1997Copyright 1997, Grant Schenck Software114 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.

July 9, 1997Copyright 1997, Grant Schenck Software115 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

July 9, 1997Copyright 1997, Grant Schenck Software116 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] (5)lineDial(x102) on new consult call [102 goes CONNECTED] (6)lineAddToConference(ConfCall, 102) [102 goes CONFERENCED] [Conf Call goes CONNECTED] Ext 100 Ext 101Ext 102 2 1, 3, 4, 6 5

July 9, 1997Copyright 1997, Grant Schenck Software117 Conference Existing Call Use the lineSetupConference(), lineDial(), lineAddToConference() and possibly linePrepareAddToConference(). Support for this type of conference is indicated in LINEADDRESSCAPS in: –dwCallFeatures LINECALLFEATURES_SETUPCONF –dwAddrCapsFlags should not have LINEADDRCAPFLAGS_SETUPCONFNULL set.

July 9, 1997Copyright 1997, Grant Schenck Software118 Conference Existing Call (1)lineMakeCall(x101) [101 goes CONNECTED] (2) lineSetupConference(101) [101 goes CONFERENCED] [Returns new conf call in ONHOLDPENDCONF state] [Returns new DIALTONE consult call] (3)lineDial(x102) on new consult call [102 goes CONNECTED] (4)lineAddToConference(ConfCall, 102) [102 goes CONFERENCED] [Conf Call goes CONNECTED] [We could add more participants] (5) linePrepareAddToConference(ConfCall) [Conf Call goes ONHOLDPENDCONF] [Returns new DIALTONE consulting call] (6)lineDial(x103) on new consult call [103 goes CONNECTED] (7)lineAddToConference(ConfCall, 103) [103 goes CONFERENCED] [Conf Call goes CONNECTED] Ext 100 Ext 101Ext 102 1 2, 4, 5, 7 3 Ext 103 6

July 9, 1997Copyright 1997, Grant Schenck Software119 No Hold Conference Uses the lineSetupConference() and/or lineAddToConference(). Support for this type of conference is indicated in LINEADDRESSCAPS in: –dwCallFeatures LINECALLFEATURES_SETUPCONF, _ADDTOCONF –dwCallFeatures2 LINECALLFEATURE2_NOHOLDCONFERENCE.

July 9, 1997Copyright 1997, Grant Schenck Software120 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.

July 9, 1997Copyright 1997, Grant Schenck Software121 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.)

July 9, 1997Copyright 1997, Grant Schenck Software122 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

July 9, 1997Copyright 1997, Grant Schenck Software123 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.

July 9, 1997Copyright 1997, Grant Schenck Software124 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.

July 9, 1997Copyright 1997, Grant Schenck Software125 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.

July 9, 1997Copyright 1997, Grant Schenck Software126 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.

July 9, 1997Copyright 1997, Grant Schenck Software127 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.

July 9, 1997Copyright 1997, Grant Schenck Software128 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.

July 9, 1997Copyright 1997, Grant Schenck Software129 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.

July 9, 1997Copyright 1997, Grant Schenck Software130 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

July 9, 1997Copyright 1997, Grant Schenck Software131 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

July 9, 1997Copyright 1997, Grant Schenck Software133 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.

July 9, 1997Copyright 1997, Grant Schenck Software134 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.

July 9, 1997Copyright 1997, Grant Schenck Software135 TSP Code for Tacking On Data void 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 data TackOnData(lpCallInfo, L"3047", &lpCallInfo->dwCalledIDSize);

July 9, 1997Copyright 1997, Grant Schenck Software136 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().

July 9, 1997Copyright 1997, Grant Schenck Software137 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.

July 9, 1997Copyright 1997, Grant Schenck Software138 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().

July 9, 1997Copyright 1997, Grant Schenck Software139 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.

July 9, 1997Copyright 1997, Grant Schenck Software140 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.

July 9, 1997Copyright 1997, Grant Schenck Software141 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().

July 9, 1997Copyright 1997, Grant Schenck Software142 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.

July 9, 1997Copyright 1997, Grant Schenck Software143 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()

July 9, 1997Copyright 1997, Grant Schenck Software144 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.

July 9, 1997Copyright 1997, Grant Schenck Software145 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.

July 9, 1997Copyright 1997, Grant Schenck Software146 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.

July 9, 1997Copyright 1997, Grant Schenck Software148 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.

July 9, 1997Copyright 1997, Grant Schenck Software149 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.

July 9, 1997Copyright 1997, Grant Schenck Software150 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)

July 9, 1997Copyright 1997, Grant Schenck Software152 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().

July 9, 1997Copyright 1997, Grant Schenck Software153 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.

July 9, 1997Copyright 1997, Grant Schenck Software156 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.

July 9, 1997Copyright 1997, Grant Schenck Software158 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.

July 9, 1997Copyright 1997, Grant Schenck Software160 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.

July 9, 1997Copyright 1997, Grant Schenck Software161 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.

July 9, 1997Copyright 1997, Grant Schenck Software162 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()

July 9, 1997Copyright 1997, Grant Schenck Software165 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.

July 9, 1997Copyright 1997, Grant Schenck Software166 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.

July 9, 1997Copyright 1997, Grant Schenck Software167 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.

July 9, 1997Copyright 1997, Grant Schenck Software168 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.

July 9, 1997Copyright 1997, Grant Schenck Software169 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().

July 9, 1997Copyright 1997, Grant Schenck Software170 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.

July 9, 1997Copyright 1997, Grant Schenck Software171 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())...

July 9, 1997Copyright 1997, Grant Schenck Software172 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.

July 9, 1997Copyright 1997, Grant Schenck Software173 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.

July 9, 1997Copyright 1997, Grant Schenck Software174 Putting this all together LONG 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 Server m_pCTIProtocolSocket->Write(m_CTICallID, MSGTYPE_HOLD); // Complete async as sync (*g_Provider->m_lpfnCompletionProc)(dwRequestID, 0); return (LONG)dwRequestID; }

July 9, 1997Copyright 1997, Grant Schenck Software175 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.

July 9, 1997Copyright 1997, Grant Schenck Software176 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 “ DebugLevel”, e.g., “Tapi32DebugLevel”, “TapisrvDebugLevel”, etc.

July 9, 1997Copyright 1997, Grant Schenck Software177 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.

July 9, 1997Copyright 1997, Grant Schenck Software179 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.

July 9, 1997Copyright 1997, Grant Schenck Software180 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, California July 9th, 1997 Grant Schenck, Grant Schenck Software.

Similar presentations

Presentation on theme: "July 9, 1997Copyright 1997, Grant Schenck Software1 TAPI 2.0/2.1 Genoa Technology San Jose, California July 9th, 1997 Grant Schenck, Grant Schenck Software."— Presentation transcript:

Similar presentations

About project

Feedback

Log in

Auth with social network:

July 9, 1997Copyright 1997, Grant Schenck Software1 TAPI 2.0/2.1 Genoa Technology San Jose, California July 9th, 1997 Grant Schenck, Grant Schenck Software.

Similar presentations

Presentation on theme: "July 9, 1997Copyright 1997, Grant Schenck Software1 TAPI 2.0/2.1 Genoa Technology San Jose, California July 9th, 1997 Grant Schenck, Grant Schenck Software."— Presentation transcript:

Similar presentations

About project

Feedback