Altigen AltiAgent ActiveX User Guide

AltiAgent ActiveX Programmer’s Guide

Thisdocument provides instructions on configuring andusing ActiveX controls with AltiAgent. API
reference information is also provided.

Contents

UsingAltiAgentActiveXControlObject...........................................2

UnderstandingKeyFiles......................................................2

BasicProcedureofUsingAltiAgentActiveX......................................2

UsingAppWizardtoCreateaProject............................................3

Inserting AltiCtrl into dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

HandleAltiCtrlEvents........................................................3

AltiCtrl Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

AltiAgent ActiveX Control API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

StartAltiCtrl................................................................4

AltiCtrl Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

CallNotify..................................................................4

AltiCtrlMethods...............................................................6

SetUserData................................................................6

GetUserData................................................................6

SetIVRData.................................................................7

GetIVRData................................................................8

SetURLData................................................................9

GetURLData................................................................9

SetCallerName.............................................................10

GetExtNumber.............................................................11

MakeCall .................................................................11

GetTrunkAccessCode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Related Documentation

• AltiGen - AltiAgent Manual - information on installation and configuration of the AltiAgent

client system software.

02/2004

AltiClient ActiveX Programmer’s Guide 2

Using AltiAgent ActiveX Control Object

The AltiAgent ActiveX Control Object is an ActiveX Object. It will work with AltiAgent, getting
call-related information from AltiAgent, which acts as a server, and implement actions based on the
call information, for example, popping up corresponding customer information and logging caller
ID into a database.

This document contains descriptions of AltiAgent ActiveX Control Object files and type library,
followedbyexamplesinVC++.

Understanding Key Files

• AltiCtrl.tlb—this type library file contains functions within the AltiCtrl ActiveX Object.

Methods contained in this type library need to be used directly by Visual C++ developers. In
Visual Basic, type library functions are handled automatically at run time.

• AltiCtrl.ocx—thirdpartyapplicationsuse this ActiveX control moduleto developapplications.

It needs to be registered before starting application development.

Note: Before using AltiAgent AltiCtrl to develop your application, you need to register

AltiCtrl.ocx using RegSvr32.exe first. Because this object will work with AltiAgent, you
need to run an AltiAgent client when you develop and run your application on the same
machine.

Basic Procedure of Using AltiAgent ActiveX

To use ActiveX control object with AltiAgent:

1. Make sure AltiAgent is installed on the client desktop PC.

2. Copy AltiCtrl.ocx file from AltiAgent API directory to Windows system32 (NT/2000) or
system (98) directory.

3. Bring up command prompt and register altictrl.ocx

4. Edit VB or VC sample code to interface with destination client application.

5. Compile customized code to an executable file.

6. Copy that executable file to the same directory as AltiAgent.

AltiClient ActiveX Programmer’s Guide 3

Using AppWizard to Create a Project

Use AppWizard to create a dialog based MFC project:

1. Choose MFC AppWizard (exe) and create a new win32 project named "ExampleVc"; press
Next.

2. Set Dialog based as the type of the Application; press Next.

3. Keep ActiveX Control and Windows Sockets checkboxes checked.

4. The program uses shared MFC DLLs (AltiCtrl uses shared MFC DLLs).

5. Click Finished to create the project.

Inserting AltiCtrl into dialog

AltiCtrl is an ActiveX Control without any GUI. It is invisible and can be inserted anywhere

1. Open the main dialog (IDD_EXAMPLEVC_DIALOG)

2. Click the right mouse button on the dialog and a context menu will display.

3. Choose Insert ActiveX Control to display the Insert ActiveX Control dialog box.

4. Select AltiCtrl Control and click OK to add it.

5. Place the control at a suitable location and size it as desired. P lease note that the control is
invisible at runtime.

6. Identify the control as IDC_ALTICTRLCTRL1 (default value).

Handle AltiCtrl Events

To add an event process function:

1. Open Class Wizard and go to Message Maps page.

2. Set CExampleVcDlg as current class.

3. Set IDC_ALTICTRLCTRL1 as current selection of “Object Ids” list box and all AltiCtrl
Events will be displayed in Message list box.

4. Add member functions for the events you would like to handle.

5. Add code for these member functions.

AltiCtrl Methods

When adding a function to handle an AltiCtrl Event, you don't need to worry about how and when
the function is called. AltiCtrl will perform the event call back for you.

When using the AltiCtrl properties of getting and setting methods, you can use AltiCtrl to set or
monitor a Call property. Before doing so, you must add a member variable associated with this
control.

To add a member variable associated with this control:

1. Open Class Wizard and go to Member Variables page.

2. Set CExampleVcDlg as current class.

3. Double-click IDC_ALTICTRLCTRL1 of Control Ids list box and a message box will be
displayed to prompt you to add the ActiveX Control AltiCtrl into the project. ClickOKto have
Developer Studio generate a C++ wrapper class.

4. When the Confirm Classes dialog box appears, set CAltiCtrl as the class name and click OK.

AltiClient ActiveX Programmer’s Guide 4

5. In the Add Member Variable dialog, create a member variable named m_altictrl.

6. Click OK to add it to the class. m_altictrl is now a member of CAltiCtrl.

Now, VC has created a member in class CExampleVcDlg which can be used as a general object.

AltiAgent ActiveX Control API Reference

StartAltiCtrl

Description

Start AltiCtrl on the client. This is the first step to use this AltiCtrl.

VC++ Syntax

BOOL StartAltiCtrl()

VB++ Syntax

object.StartAltiCtrl()

Return type

BOOL TRUE if connect to AltiAgent successfully; otherwise FALSE.

Remark

This function is the key of using AltiCtrl. Client cannot call the method or get any event from
AltiAgent if this function call fails.

VC++ Example

BOOL bstart= m_altictrl.StartAltiCtrl();

VB Example

Dim bstart as bool
bstart = AltiCtrl1.StartAltiCtrl()

AltiCtrl Event

CallNotify

Description

When AltiView/AltiAgent 5.0 receives a call event from AltiServ, AltiCtrl will send the event to
your application, each call will have an unique session ID, each call may several events with its
unique session ID.

Syntax

OnCallNotifyXXXXX (long ulSessionID, short uStatus, LPCTSTR
szCallerID, LPCTSTR szCallerName, LPCTSTR szCallDNIS, LPCTSTR
szWorkgroup, LPCTSTR pszDateTime, LPCTSTR pszDuration)

Parameters

ulSessionID
uStatus
szCallerID
szCallerName
szCallDNIS
pszDateTime
pszDuration

=SessionID
= Call Status
=CallerID
=CallerName
=DNIS
= Call start date and time
= Conversation duration

LINECALLSTATE_IDLE
LINECALLSTATE_OFFERING
LINECALLSTATE_ACCEPTED
LINECALLSTATE_DIALTONE
LINECALLSTATE_DIALING
LINECALLSTATE_RINGBACK
LINECALLSTATE_BUSY
LINECALLSTATE_SPECIALINFO
LINECALLSTATE_CONNECTED
LINECALLSTATE_PROCEEDING
LINECALLSTATE_ONHOLD
LINECALLSTATE_CONFERENCED
LINECALLSTATE_ONHOLDPENDCONF
LINECALLSTATE_ONHOLDPENDTRANSFER
LINECALLSTATE_DISCONNECTED
LINECALLSTATE_AA
LINECALLSTATE_VM
LINECALLSTATE_PARK
LINECALLSTATE_UNKNOWN
LINECALLSTATE_MUSICONHOLD
LINECALLSTATE_PLAYVOICEMAIL
LINECALLSTATE_CALLPENDING

0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Remark

Call status value:

AltiClient ActiveX Programmer’s Guide 5

AltiClient ActiveX Programmer’s Guide 6

AltiCtrl Methods

SetUserData

Description

Set user data for existing call. User data is used for AltiAgent to describe a call information, for
example “This call is urgent” and so on. It can be any information d efined by user.

VC++ Syntax

BOOL SetUserData(int SessionID , CString string)

VB Syntax

object.SetUserData(SessionID,string)

Parameters

SessionID [In] - unique ID for a call
String [In] - set user data for a call; maximum length is 256 bytes

Return Type

Bool - if successful TRUE; otherwise FALSE

Remark

SessionID - Session ID received from OnCallNotify event needs to be provided as input to this
function. This Session ID is valid in ring event and connect event. After Disconnect event, it is no
longer valid.

VC++ Example

CString data = _T("user data");
m_altictrl. SetUserData (ulSessionID,data);

VB Example

Dim data As String
Data = "user data"
If (AltiCtrl1.SetUserData(ulSessionID, data) = False) Then
...
Else
...
End If

GetUserData

Description

Get user data for existing call.

VC++ Syntax

CString GetUserData(int SessionID)

AltiClient ActiveX Programmer’s Guide 7

VB Syntax

object.GetUserData(SessionID)

Parameters

SessionID - [In]: unique ID for a call

Return Type

String user data for a call; maximum length is 256 bytes.

Remark

SessionID - Session ID received from OnCallNotify event needs to be provided as input to this
function. This Session ID is valid in ring event and connect event. After Disconnect event, it is no
longer valid.

VC++ Example

CString data;
data = m_altictrl.GetUserData (ulSessionID);

VB Example

Dim data As String
Data = AltiCtrl1.GetUserData(ulSessionID)

SetIVRData

Description

Set IVR data for existing call (used only in Web call). IVR data is the format of “name=value” pairs,
which can be used in Web Call and Auto Atendant; for example:

“FirstName=John&LastName=Anny&Password=hello1234” and so on.

Note

SetIVRData is a reserved API.

VC++ Syntax

BOOL SetIVRData(int SessionID, CString string)

VB Syntax

object.SetIVRData(SessionID,string)

Parameters

SessionID [In]: unique ID for a call
String [In]: Set IVR data for a call, maximum length is 256 bytes

Return Type

Bool if successful TRUE; otherwise FALSE.

Remark

SessionID - Session ID received from OnCallNotify event needs to be provided as input to this
function. This Session ID is valid in ring event and connect event. After Disconnect event, it is no
longer valid.

AltiClient ActiveX Programmer’s Guide 8

VC++ Example

CString data = _T("ivr data");
m_altictrl. SetURLData (ulSessionID,data);

VB Example

Dim data As String
Data = "ivr data"
If (AltiCtrl1.SetURLData(ulSessionID, data) = False) Then
...
Else
...
End If

GetIVRData

Description

Get IVR data for existing call.

VC++ Syntax

CString GetIVRData(int SessionID)

VB Syntax

object.GetIVRData(SessionID)

Parameters

SessionID [In]: unique ID for a call

Return Type

String IVR data for a call; maximum length is 256 bytes.

Remark

SessionID - Session ID received from OnCallNotify event needs to be provided as input to this
function. This Session ID is valid in ring event and connect event. After Disconnect event, it is no
longer valid.

VC++ Example

CString data;
data = m_altictrl.GetIVRData (ulSessionID);

VB Example

Dim data As String
Data = AltiCtrl1.GetIVRData(ulSessionID)

AltiClient ActiveX Programmer’s Guide 9

SetURLData

Description

Set URL data for existing call (used only in Web call). When a call comes to a Web site, it can
contain URL data such as “http://www.altigen.com,” so that user application can know where this
call comes from.

Note

SetURLData is a reserved API.

VC++ Syntax

BOOL SetURLData(int SessionID,CString string)

VB Syntax

object.SetURLData(SessionID,string)

Parameters

SessionID [In]: unique ID for a call
String [In] Set URL data for a call; maximum length is 256 bytes.

Return Type

Bool if successful TRUE; otherwise FALSE

Remark

SessionID - Session ID received from OnCallNotify event needs to be provided as input to this
function. This Session ID is valid in ring event and connect event. After Disconnect event, it is no
longer valid.

VC++ Example

CString data = _T("url data");
m_altictrl. SetURLData (ulSessionID,data);

VB Example

Dim data As String
Data = "url data"
If (AltiCtrl1.SetURLData(ulSessionID, data) = False) Then
...
Else
...
End If

GetURLData

Description

Get URL data for existing call

VC++ Syntax

CString GetURLData(int SessionID)

AltiClient ActiveX Programmer’s Guide 10

VB Syntax

object.GetURLData(SessionID)

Parameters

SessionID [In]: unique ID for a call

Return Type

String URL data for a call; maximum length is 256 bytes.

Remark

SessionID - Session ID received from OnCallNotify event needs to be provided as input to this
function. This Session ID is valid in ring event and connect event. After Disconnect event, it is no
longer valid.

VC++ Example

CString data;
data = m_altictrl.GetURLData (ulSessionID);

VB Example

Dim data As String
Data = AltiCtrl1.GetURLData(ulSessionID)

SetCallerName

Description

Set Caller Name for existing call

VC++ Syntax

BOOL SetCallerName(int SessionID ,CString string)

VB Syntax

object.SetCallerNameData(SessionID,string)

Parameters

SessionID [In]: unique ID for a call
String [In] Set URL data for a call, max-length is 256 bytes

Return type

Bool The value is TRUE if successful; otherwise FALSE

Remark

SessionID - Session ID received from OnCallNotify event needs to be provided as input to this
function. This Session ID is valid in ring event and connect event. While after Disconnect event , it
is no longer valid.

VC++ Example

CString name = _T("Tom");
m_altictrl.SetCallerName(ulSessionID,name);

AltiClient ActiveX Programmer’s Guide 11

VB Example

Dim data As String
Data = "Tom";
If (AltiCtrl1.SetCallerName(ulSessionID, data) = False) Then
...
Else
...
End If

GetExtNumber

Description

Get extension number which AltiAgent had been logged in.

VC++ Syntax

CString GetExtNumber()

VB++ Syntax

object.GetExtNumber()

Return type

String extension number for the AltiAgent login is 256 bytes.

VC++ Example

CString data = m_altictrl.GetExtNumber();

VB Example

Dim data as String
data = AltiCtrl1.GetExtNumber()

MakeCall

Description

Make a call through AltiAgent.

VC++ Syntax

long MakeCall(LPCTSTR pszDialNumber);

VB++ Syntax

object.MakeCall(string)

Parameters

pszDialNumber [In]: Destination telephone number, less than 32
digits

Return type

0 - Make call command is sent successfully

AltiClient ActiveX Programmer’s Guide 12

1-Unknownerroroccurs
2 - Disconnect AltiAgent
999 - Exception occurred

VC++ Example

BOOL bstart= m_altictrl. MakeCall("101");

VB Example

Dim Result as Integer
Dim dirNum As String
dirNum = "101"
Result = AltiCtrl1.MakeCall(dirNum)

GetTrunkAccessCode

Description

Get default trunk access code set in AltiAgent.

VC++ Syntax

CString GetTrunkAccessCode ();

VB++ Syntax

object. GetTrunkAccessCode()

Return type

Default trunk access code set in AltiAgent

VC++ Example

CString strTrunkAccess= m_altictrl. GetTrunkAccessCode ();

VB Example

Dim data As String
Data = AltiCtrl1.GetIVRData(ulSessionID)

Note: The ctrl will show a windowin client application. To hide window, using the following code

VC++ Example

m_altictrl.ShowWindow(SW_HIDE);

VB Sample

AltiCtrl1.Visible = TRUE

AAPG-02/2004