The so called TAPI is an abbreviation for Telephone Application Programming Interface or Telephone API which was developed together by Intel an Microsoft.

It allows applications to access telephone lines, to listen to incoming calls and to make telephone calls from the computer.

The greatest advantage of TAPI is, that it abstracts from the particular hardware of the modem, telephone, ISDN card or PBX (Private Branch eXchange) you are using.

To be able to use TAPI you must have a TAPI driver installed, which is compatible with your telephone device.

TAPI provides a complete set of commands and methods which can be used to access the particular telephone device.

And not only this. The current version 3.0 of TAPI also supports IP telephony, standards-based H.323 conferencing and IP multicast conferencing.

Why an Omnis external for TAPI

Like a developer who's name I unfortunately don't remember, said: "TAPI is a great example, how a simple thing can be made incredibly complicated." This is true especially seen from a developer's point of view.

Even in C/C++ it's not quite easy to deal with TAPI. But in Omnis Studio and much more Omnis 7.x it's more or less impossible to get TAPI working.

The reason must be seen in the way of interface TAPI provides to the user. It is a huge set of Functions and methods which are encapsulated within a Windows DLL called tapi32.dll.

Although most DLLs and their functions (the easy ones) can be called from Omnis, the TAPI DLL is an exception because it uses input/output parameters and data structures which can't be accessed from within Omnis because the use C-type variable structures or need callback functions in the application.

So we decided to give Omnis developers easy and uncomplicated to the telephony API by building OmTAPI, a classic style Omnis External which can be used with Omnis Classic and Omnis Studio.

It’s a wrapper for all that complicated stuff within TAPI and gives you a set of 14 external commands, which should be sufficient, to do all the common stuff, your customers probably ask you to implement in your application.

What OmTAPI does

In short terms, the external OmTAPI commands allow you to:

Initialize the TAPI interface
Get a list of all TAPI devices installed on a particular system
Retrieve information about each device/line
Select a device/line
Configure a device/line
Configure the system dialing parameters
Make a call on the device/line selected
Monitor the TAPI status messages
Listen to incoming calls on the selected device/line
Retrieve the telephone number of the caller, to identify him by a database search
(if the device/line supports this feature and if the caller number is transferred to you)

Installation

Just extract the ZIP archive provided an copy the two DLL's

- omtapi.dll

- evtapi.dll

in the EXTERNAL folder located in the program directory of your Omnis installation.

The license number must be saved to a file called omtapi.txt which resides directly in the Omnis application directory where omnis.exe is located also.

After restarting Omnis, the TAPI…-commands should show up in the External commands group.

OmTAPI Commands

The OmTAPI external consists of a set of 14 external command, which give you access to the most common functions of the TAPI interface. The sample application OMTAPI.LBS provided with OmTapi is fully documented shows the use of each command.

Important:

OmTAPI uses the hash variables #60 and #S5 for internal purposes. So don't use #60 and #S5 for storing permanent values in your application. They will be changed.

TapiGetNumLines()

Parameters: None

Return Value: Integer, Number of Lines useable for TAPI communication

Description

TapiGetNumLines returns the number of TAPI devices installed in the users system in an integer value. If the return code is zero, there are no TAPI devices installed.

Important:

TapiGetNumLines also initializes OmTAPI, so it should ALWAYS be the first command, when working with OmTAPI.

Example:

; The next line is necessary to initialize the

; TAPI Interface class in the External DLL.

; The initialized class will remain instanciated until it

; will be destroyed or Omnis is closed

TapiGetNumLines Returns iNumLines

If iNumLines=0

OK message TAPI {No Lines available}

Else

TapiSetEventHandler ("cTAPI/TAPIEventHandler")

; This Class/Method (or Format/Procedure in Omnis Classic)

; will be called by OmTAPI to signal certain events

; Default is: cTAPI/TAPIEventHandler, whereby cTAPI may

; be a noninstanciated Class in Studio (a Code Class)

; or a Format (Window or Menu) in Omnis Classic

End If

TapiGetLineList(lList)

Parameters: List variable

Return Value: Integer

Description

TapiGetLineList() returns an Omnis list which contains the number and the name of each usable TAPI device. When TapiGetLineList() succeeds, it returns kTrue / 1. In case of an error, zero / kFalse is returned.

The list variable is to be defined before calling TapiGetLineList. The first column is an integer, the second a character field with a length of at least 20 characters. If the line name retuned by OmTapi is longer, than the limit defined, the name will be truncated, no error occurs.

Important:

Numbering in the list starts with one to correspond with the numbering of the current line (#L resp. mylist.$line) in Omnis. Internally TAPI starts counting with zero.

Example:

Do iTapiLineList.$define(lLineNr,lLineName)

TapiGetLineList (iTapiLineList) Returns lRet

If lRet>0

Do iTapiLineList.$line.$assign(1)

Do $cinst.$objs.DL_LineList.$redraw()

End If

After calling TapiGetLineList, the list of TAPI devices could look like this:

TapiConfigDialog(iNumLine)

Parameters: Number of line, integer

Return Value: Integer

Description

TapiConfigDialog opens the configuration dialog of the selected TAPI line, if available. No each TAPI device – like the RAS VPN line - is configurable and so not each TAPI has a configuration dialog. This configuration dialog is "built in" in the particular TAPI driver. Its not an Omnis dialog.

TapiConfigDialog returns kTrue if successful, also if there is no configuration dialog. If no configuration dialog is available, an OK Message Box appears.

When using OmTAPI together with a PBX, which probably is the most frequent use of this command, this is the place where you tell OmTAPI to use the telephone next to you on your desk.

The screenshot above shows the configuration dialog of an AGFEO AS 40 ISDN PBX, which is very common in Europe. Here the internal number (14) is combined with a nickname for each user connected to the PBX.

Example:

TapiConfigDialog (iLineNum) Returns lRet

TapiDialParams(iNumLine, [cExampleNumber])

Parameters: Number of line, integer, [Number to test, character [30]]

Number to dial, character [32]

Return Value: Integer

Description

This command opens the windows built in dialog for telephone and modem options. for the selected line. It returns kTrue if successful, otherwise kFalse.

Here you can determine the dialing rules, for example the digit to prefix, to get a public or long distance line.

As an optional second parameter, you can pass a string containing a telephone number, to show how TAPI will dial it (with leading zeros etc.) The number passed will be displayed left at the bottom of the configuration dialog.

TapiDialParams returns kTrue if successful, otherwise zero.

Example:

TapiDialParams (iLineNum,cNumbertoTest) Returns lRet

TapiGetLineParams(iLineNum, lList)

Parameters: Number of Line, List with results

Return Value: Integer

Description

TapiGetLineParams returns a list given as the second parameter, which contains a number of selected properties for the selected line. The list has to be defined before calling TapiGetLineParams. The first column is character value with a length of 40 characters, the second one a character value with a length of 100 characters.

Important:

TapiGetLineParams also selects the line for some commands i.e. TapiSupportVoiceCalls, which do not require a line number as parameter.

The TAPI line number shown in the screen shot below is always the line number used in Omnis minus one because TAPI internally starts counting with zero.

TapiGetLineParams returns true if successful, otherwise zero.

Most of the the names of the parameters and values returned in the list are self-explanatory. One of the most interesting parameters is the last one. It indicates, if the line is able to listen to incoming calls.

If you're interested in the meaning of the remaining parameters, please visit http://msdn.microsoft.com/library/default.asp?url=/library/en-us/tapi/tapi2/linedevcaps_str.asp

It explains the contents of a LINEDEVCAPS C-Structure which is returned by the genuine TAPI function.

Example:

Do iTapiLineParamList.$define(iParamName,lParamValue)

TapiGetLineParams (pLineNum,iTapiLineParamList) Returns lRet

If lRet

Do $cinst.$objs.HL_LineParams.$redraw()

TapiSupportVoiceCalls Returns lRet

Do $cinst.$objs.B_Dial.$enabled.$assign(lRet)

If int(iTapiLineParamList.16.lParamValue)=kTrue

Do $cinst.$objs.B_Listen.$enabled.$assign(kTrue)

Else

Do $cinst.$objs.B_Listen.$enabled.$assign(kFalse)

End If

TapiSupportVoiceCalls()

Parameters: None

Return Value: Integer

Description

TapiSupportVoiceCalls indicates, if the line selected with TapiGetLineParams does support voice calls. The return value is kTrue if yes, otherwise zero.

Example:

See TapiGetLineParams

TapiSetEventHandler(cEventHandler [ClassName/MethodName])

Parameters: Character, optional [Class or Format name/Method name]

Return Value: Integer

Description

TapiSetEventHandler defines a callback method (or procedure) in Omnis which is called by the OmTAPI external to post back status messages, information or error codes into Omnis studio.

The optional parameter is a character string containing the name of the class resp. format containing the method/procedure and the name of the method/procedure.

If omitted the default value is:

cTAPI/TAPIEventHandler

In Omnis Classic the procedure can reside within a window or menu format. In Omnis Studio it should reside within a code Class.

Why do we have to set an event handler for TAPI? TAPI is able to informs the user about a lot of things i.e. the status of call being processed etc. BUT most of the TAPI functions are asynchronous and also work with C-type callbacks. This means, that after calling a TAPI function, i.e. dialing a phone number, the control is returned to the calling application (Omnis) immediately. But nevertheless, TAPI does it's job in an own thread. To get informed about the calling status, you must tell TAPI, respectively OmTAPI the name/address of a function to call, if there is some information for the user.

Example:

TapiSetEventHandler ("cTAPI/TAPIEventHandler") Returns lRet

The method TAPIEventHandler could look like this:

Do $iwindows.wTapiTest.$addLintoActionList(#60,#S5)

I the Method $addLintoActionList in the Window instance wTapiTest, the information contained in #60 and #S5 are added to a list and a window redraw is done.

The storing of the values in #60 and #S5 is done directly by the OmTAPI external, so please don't use #60 and #S5 for storing any other values, they will be overwritten whenever an information is passed over to Omnis.

Values:

#60 can contain the values from 1 to 3

1 Status information

2 Error

3 Incoming call

#S5 contains an explanation or information, or in case of an incoming call, the caller's telephone number, if the PPBX supports this and if the caller doesn't suppress his number being transferred.

TapiMakeCall(cNumberToDial, iLineNum)

Parameters: Character, phone number to call [32]

Line number

Return Value: Integer

Description

TapiMakeCall starts dialing a call to the TAPI line number given as second parameter. The number (maximum 32 characters) is the first parameter.

It returns kTrue if successful, otherwise it returns kFalse.

TapiMakeCall is a typical example for an asynchronous TAPI function. Control is returned immediately to Omnis. Status messages are signaled to Omnis by using the method given with TapiSetEventHandler.

Read more about this in the description to TapiGetMessages().

Example:

Do iMsgList.$clear()

TapiMakeCall (iNumbertoDial,iLineNum) Returns lRet

If lRet

Do $cobj.$enabled.$assign(kFalse)

Do $cinst.$objs.B_Hangup.$enabled.$assign(kTrue)

End If

TapiHangupCall()

Parameters: None

Return Value: Integer

Description

Any outgoing call will be terminated. Returns kTrue if successful, otherwise it returns kFalse.

TapiShowStatusWnd(bShow,[iXPos,iYPos,cTitle,iFontSize])

Parameters: Boolean bShow,

[Integer x-position,

Integer y-position,

character Title,

Integer fontsize]

Return Value: Integer

Description

This command is very useful for developing a TAPI application but maybe also for the end user.

With TapiShowStatusWnd, a status windows will be opened, which displays all TAPI messages and Status events. The status window also will be in front of all Omnis windows.

The window opened is not an Omnis window, its generated by the external and so it cannot be modified.

The first parameter is boolean and results the window to be shown (kTrue) or to be closed (kFalse), if its open.

The second and all following parameters are optional. With iXPos and iYPos you set the window position in pixels relative to the upper left corner of the whole screen, not the Omnis main window.

The forth parameter sets the status window title.

The fifth parameter sets the font size of the messages displayed. If omitted default values will be used.

Returns kTrue if successful, otherwise it returns kFalse.

Note: If the status window is closed successfully, TapiShowStatusWnd returns kTrue also.

TapiListenIncomingCall(iNumLine)

Parameters: Integer, number of line

Integer, LinePrivileges

Return Value: Integer

Description

This command switches OmTAPI into the listening mode. Incoming calls on the line selected by the integer parameter iNumLine will be signaled and the caller's number – if available – will be passed over to Omnis with a status value of 3.

The first parameter ist the number of the line to use.

The second parameter specifies the privilege the application wants for the calls it is notified for. This parameter can be a combination of the LINECALLPRIVILEGE_* constants.

Value Description

0 - The application can make only outgoing calls.

1 - The application can monitor only incoming and outgoing calls.

2 - The application can own only incoming calls of certin modes.

This value must be given because not each line/device can be switched to listening mode with the same values. Modems i.e. need a value of 1, ISDN PBX devices a value of 2.

Returns kTrue if successful, otherwise it returns kFalse.

Note: While listening, you also can make outgoing calls. Both functions will not interfere.

TapiCloseListenLine()

Parameters: None

Return Value: Integer

Description

OmTAPI will stop listening to incoming calls on the line selected with TapiListenIncomingCall.

Returns kTrue if successful, otherwise it returns kFalse.

TapiGetMessages()

Parameters: None

Return Value: None

Description

This command is a little hard to explain because it needs some understanding of the internal functions of the TAPI interface.

Like mentioned above, the TAPI interface has some asynchronous functions.

But that's not all. To make it even more complicated, some TAPI events and status messages appear a (relatively) long time after returning control back to Omnis. And due to the architecture of the Omnis external API, an external cannot make a callback to Omnis without having a valid callback handle. So, normally, a lot of things happening with TAPI, Omnis would never be informed about.

To avoid this, OmTAPI uses a trick and this is the reason why you have to copy a second DLL called evtapi.dll to the externals folder.

If OmTAPI, which is active all the time after you it was initialized with TapiGetNumLines(), detects an event and there is no valid callback handle to Omnis, the status information will be put on a stack and it generates an own user defined Windows event, addresses it to Omnis (because we have the handle to the main application window) and puts it into the Windows internal message queue. evtapi.dll is the event handler within Omnis which receives this event and has to be activated with the command

Load event handler EvTapi ("cTAPI/TAPIGetMsg")

In the example, the parameter cTAPI/TAPIGetMsg points to a procedure/method TAPIGetMsg in a menu format (Classic) or a code class (Studio).

This method only has one line an this is

TapiGetMessages

and causes OmTAPI now to call the method set with TAPISetEventHandler to post all status messages and information on the stack back to Omnis, because now we again have a valid callback handle to Omnis.

This sounds a little complicated and tricky and in fact, it is. But if you look at the example library provided with OmTAPI, its easy to use.

TapiShutDown ()

Parameters: None

Return Value: Integer

Description

Shuts down the OmTAPI Interface completely. Listening and all outgoing calls will be terminated.

Returns kTrue if successful, otherwise kFalse. If you want to reuse OmTAPI after TapiShutdown, Omnis has to be restarted.

Normally you won't have to use this command, all TAPI activity is terminated also, when you close Omnis without using this command.

TapiAbout()

Parameters: None

Return Value: None

Description

Displays a message box with Copyright and license information and the serial number.

FAQ

1. Will there be a version of OmTAPI for the Macintosh, Linux or Sun Solaris?

No, since TAPI is a windows specific technology, there will be only a windows version.

2. What are the limitations of the demo version?

There are four limitations in the demo version.

It runs for a trial period of 30 days.
It will only work in the development environment, not in the runtime or a webserver runtime
When an incoming call is signaled, the digits in the second half of the caller's number (if transferred) will be replaced by the letter 'x'.
There are only 5 outgoing call possible per Omnis session. The Omnis has to be restarted

These limitations allow full testing of OmTAPI but (that's the intention) not the practical use within a production environment.