Avaya IP Office CTI Link, IP Office CTI Link Lite, IP Office CTI Link Pro, IP Office DevLink Programmer's Manual

IP Office CTI Link

DevLink Programmer’s Guide

40DHB0002UKAD Issue 11a (14th June 2005)

DevLink Programmer’s Guide Page iii
IP Office CTI Link 40DHB0002UKAD Issue 11a (14th June 2005)

Table Of Contents

CTI DevLink ................................................................................................................................ 5

Overview..................................................................................................................................................... 5

IP Office CTI Link Lite................................................................................................................................. 5

IP Office CTI Link Pro................................................................................................................................. 5

DevLink....................................................................................................................................................... 6

Using the DevLink DLL............................................................................................................................... 6

Using DevLink with Microsoft Visual C++ .............................................................................................. 6

Using DevLink with Borland Delphi........................................................................................................ 6

Connecting to an IP Office using DevLink............................................................................... 7

Connecting ................................................................................................................................................. 7

Example: Connecting to IP Office in "C"..................................................................................................... 8

Example: Connecting to IP Office in Delphi................................................................................................ 9

Disconnecting ........................................................................................................................................... 10

DevLink Real-Time Event Stream ........................................................................................... 11

DevLink Real-Time Event Stream ............................................................................................................ 11

S events.................................................................................................................................................... 12

Field 25 Cause Codes ......................................................................................................................... 15

D events ................................................................................................................................................... 16

A events.................................................................................................................................................... 16

DevLink reference.................................................................................................................... 17

Functions .................................................................................................................................................. 17

DLOpen................................................................................................................................................ 17

DLClose ............................................................................................................................................... 18

DLRegisterType2CallDeltas................................................................................................................. 19

Callbacks .................................................................................................................................................. 20

COMMSEVENT ................................................................................................................................... 20

CALLLOGEVENT ................................................................................................................................ 21

Appendices............................................................................................................................... 23

DEVLINK.PAS .......................................................................................................................................... 23

DEVLINK.H............................................................................................................................................... 24

Index.......................................................................................................................................... 25

DevLink Programmer’s Guide Page 5
IP Office CTI Link 40DHB0002UKAD Issue 11a (14th June 2005)

CTI DevLink

Overview

IP Office DevLink is part of the IP Office CTI Link Software Development Kit. The IP Office CTI Link is
available in Lite and Pro versions, which provide run-time interfaces for applications to use. The
Software Development Kit (SDK) provides documentation on both Lite and Pro interfaces for software
developers.

Both the Lite and Pro offerings are the same program. The additional functionality provided by IP Office
CTI Link Pro is enabled when the CTI Link Pro licence key is installed.

This manual provides a tutorial and reference to the DevLink Pro interface, as well as providing example
source code.

IP Office CTI Link Lite

IP Office CTI Link Lite is a free of charge offering, and contains the following component:

• TAPILink Lite

This component implements Microsoft TAPI, and allows programs to control one telephone line
per PC. It provides simple CTI, including answer, hangup, make-call, transfer, and provides
CLI/ANI for screen-popping. Please see the TAPILink Developers Guide for more details on
TAPILink Lite and TAPILink Pro.

Note that the first version of CTI Link Lite contained DevLink Lite (DevLink version 1.0.0.3) which
provided a Call Logging interface. This has been superseded by IP Office SMDR, which is available on
the IP Office 1.3 Admin CD. DevLink version 1.0.0.4 no longer exports the Call Logging interface.

IP Office CTI Link Pro

IP Office CTI Link Pro includes all of the Lite functionality and is accessed via a licence key. It contains
the following components:

• TAPILink Pro

This component provides both first-party and third-party TAPI control of telephony devices. In
addition to the functionality provided by TAPILink Lite, it also adds the ability to receive
information on ACD queues, hunt groups, and provides additional advanced functionality. Please
see the TAPILink Developers Guide for more details on TAPILink Lite and TAPILink Pro.

• DevLink Pro

This component provides a real-time event stream. The real-time event stream provides
information on telephone activity as and when that activity occurs, and also provides information
on trunk activity.

Printed Documentation

DevLink Programmer’s Guide Page 6
IP Office CTI Link 40DHB0002UKAD Issue 11a (14th June 2005)

DevLink

DevLink provides a programming interface which complements the Microsoft TAPI interfaces provided
by TAPILink Lite and Pro:

• Real-time event stream

The Real-time event stream is enabled by installing the CTI Pro licence key onto the system unit.

The DevLink DLL, which is included on the User CD-ROM should be installed with the licence key.
DevLink enables third-party applications, such as call recorders to use information provided by the
telephone system. Please refer to the IP Office CTI Link Installation Manual for installation instructions.

When the DevLink component is installed, a Windows Dynamic Link Library, DEVLINK.DLL is installed,
by default, into "Program Files/Avaya/IP Office/DEV Link" directory. Programs using this interface simply
need to link to this library and use it's functions.

Notes:

1. Any application that uses the DevLink DLL should include it in the application installation script.
As the DLL is not a COM component, no registration is necessary. The DLL does not require any
registry settings or supporting files.

2. When developing an application that uses the DLL, the DevLink header file (devlink.h) and
appropriate library file (devlink.lib or devlinkomf.lib) should be copied to the same directory as the
project source files. The devlink.lib library file contains export symbols in COFF format which can
be used with projects written in Visual C++. The devlinkomf.lib library file contains export symbols
in OMF format for other linkers.

Using the DevLink DLL

DEVLINK.DLL can be used in any language that supports Dynamic Link Libraries (DLLs), e.g. Microsoft
Visual C++ or Borland Delphi.

DevLink allows developers to request call-backs, which will be generated when significant events occur.
For the real-time event stream, this occurs at various stages throughout a call's lifetime. Both telephony
calls and data calls are included in the events generated.

Please note that all application call-backs made on a thread which DevLink creates. As a result,
consideration must be given by programmers to ensure that all functions called from within a call-back
are thread-safe.

Using DevLink with Microsoft Visual C++

Appendix A contains the DEVLINK.H file which should be used with Microsoft Visual C++. Programs
written in Microsoft Visual C++ should link to the DEVLINK.LIB library.

Using DevLink with Borland Delphi

Appendix B contains the DEVLINK.PAS file which should be used with Borland Delphi. Programs written
using Borland Delphi should use DEVLINK.PAS, which links directly to the DEVLINK.DLL library.

DevLink Programmer’s Guide Page 7
IP Office CTI Link 40DHB0002UKAD Issue 11a (14th June 2005)

Connecting to an IP Office using DevLink

Connecting

DevLink supports connection to multiple IP Office systems at the same time. To connect to an IP Office
system, the DLOpen() function must be called:

LONG DLOpen(
LONG pbxh,
TEXT *pbx_address,
TEXT *pbx_password,
TEXT *reserved1,
TEXT *reserved2,
COMMSEVENT cb);

The application-supplied pbxh handle is used internally by DevLink to track the connected IP Office
System. Each connected system must have a different pbxh handle, supplied by the application.

The pbx_address field is the IP address of the IP Office system unit. A value of "255.255.255.255" can
be used, in which case DevLink will broadcast to locate an IP Office system unit.

Notes:

1. If DevLink is being used to control more than one IP Office system at the same time, then the
specific IP address of the IP Office must be used.

2. The cb parameter (Communications Status Callback) is required, and must not be set to NULL.
The return result from DLOpen () does not necessarily indicate whether or not the connection to
the system unit was successful. If the connection attempt succeeds, then a COMMSEVENT
callback will be generated, indicating that connection to the system has succeeded.

3. The pbx_password parameter should be the monitor password of the switch, not the system
password.

4. The reserved1 and reserved2 parameters are for future expansion, and should be set to NULL
(nil in Delphi).

Printed Documentation

DevLink Programmer’s Guide Page 8
IP Office CTI Link 40DHB0002UKAD Issue 11a (14th June 2005)

Example: Connecting to IP Office in "C"

Note that the "systempassword" in the call to DLOpen () should be replaced with your unit's actual
system password.

#include <windows.h>
#include <stdio.h>
#include "devlink.h"
LONG hEvent;
DWORD dwCommsEvent;
BOOL bStarting;
void CALLBACK HandleCommsEvent( LONG pbxh, DWORD comms_evt, DWORD parm1 )
{
switch( comms_evt ) {
case DEVLINK_COMMS_OPERATIONAL:
// we are working fine... fall through
case DEVLINK_COMMS_NORESPONSE:
// system not found (initial connection),
// or network connection lost (rebooted?)
// fall through...
case DEVLINK_COMMS_REJECTED:
// incorrect system password specified...
if( bStarting ) {
dwCommsEvent = comms_evt;
SetEvent( hEvent );
}
else {
// insert your code here...
}
break;
case DEVLINK_COMMS_MISSEDPACKETS:
// Indicates that the system is under
// heavy load. IP Office always prioritises
// data routing and call handling above CTI events.
// (parm1 contains the number of packets missed)
break;
}
}
int main(int argc, char* argv[])
{
printf( "connecting...");
bStarting = TRUE;
hEvent = CreateEvent( NULL, FALSE, FALSE, NULL );
DLOpen( 0,
"255.255.255.255"
"systempassword",
NULL,
NULL,
HandleCommsEvent );
dwCommsEvent = DEVLINK_COMMS_NORESPONSE;
WaitForSingleObject( hEvent, 10000 ); // 10 seconds
bStarting = FALSE;
if( dwCommsEvent == DEVLINK_COMMS_OPERATIONAL ) {
printf("Connected OK\n");
}
else {
printf("Error connecting to IP Office\n");
}
DLClose( 0 );
CloseHandle( hEvent );
return 0;
}

Connecting to an IP Office using DevLink

DevLink Programmer’s Guide Page 9
IP Office CTI Link 40DHB0002UKAD Issue 11a (14th June 2005)

Example: Connecting to IP Office in Delphi

Note that the "systempassword" in the call to DLOpen () should be replaced with your unit's actual
system password.

unit Unit1;
interface
uses
Windows, Messages, SysUtils, Classes, Graphics, Controls, Forms, Dialogs,
StdCtrls;
type
TForm1 = class(TForm)
Button1: TButton;
procedure Button1Click(Sender: TObject);
procedure Button2Click(Sender: TObject);
private
{ Private declarations }
public
{ Public declarations }
end;
var
Form1: TForm1;
implementation
uses
devlink;
{$R *.DFM}
var
hEvent : THANDLE;
dwCommsEvent : DWORD;
bStarting: boolean;
procedure HandleCommsEvent( pbxh : LongInt;
Comms_status : DWORD;
Parm1 : DWORD ); stdcall;
begin
case Comms_status of
DEVLINK_COMMS_OPERATIONAL,
DEVLINK_COMMS_NORESPONSE, DEVLINK_COMMS_REJECTED:
begin
if bStarting then
begin
dwCommsEvent := comms_status;
SetEvent( hEvent );
end;
end;
DEVLINK_COMMS_MISSEDPACKETS:
begin
// parm1 indicates the number of packets missed...
end;
end;
end;
procedure TForm1.Button1Click(Sender: TObject);
begin
bStarting := TRUE;
hEvent := CreateEvent( nil, FALSE, FALSE, nil );
DLOpen( 0, '255.255.255.255', 'systempassword', nil, nil, - HandleCommsEvent
);
dwCommsEvent := DEVLINK_COMMS_NORESPONSE;
WaitForSingleObject( hEvent, 10000 ); // 10-second timeout
bStarting := FALSE;
if dwCommsEvent = DEVLINK_COMMS_OPERATIONAL then
begin
ShowMessage('Connected OK');
end
else
begin