Altigen AltiAgent ActiveX Manual

AltiAgent ActiveX Programmer’s Guide
Thisdocument provides instructions on configuringand using ActiveXcontrols with AltiAgent. API
reference information is also provided.
Contents
Using an AltiAgent ActiveX Control Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2
Understanding Key Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2
Basic Procedure to Use an ActiveX Object with AltiAgent. . . . . . . . . . . . . . . . . . . . . . . . . . . .2
Using AppWizard to Create a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Inserting AltiCtrl into dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Handle AltiCtrl Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
AltiCtrl Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
AltiAgent ActiveX Control API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
StartAltiCtrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
AltiCtrl Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
CallNotify. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
AltiCtrl Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
SetUserData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
GetUserData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
SetIVRData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
GetIVRData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
SetURLData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
GetURLData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
SetCallerName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
GetExtNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
MakeCall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
GetTrunkAccessCode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Related Documentation
• AltiGen AltiAgent Manual - information on installation and configuration of the AltiAgent
client system software.
02/2008

2 AltiAgent ActiveX Programmer’s Guide
Using an 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,
followed by examples in VC++ and VB.
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—third party applicationsusethisActiveX controlmodule to develop applications.
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 to Use an ActiveX Object with AltiAgent
To use ActiveX control object with AltiAgent:
1. Make sure AltiAgent is installed on the client desktop PC.
2. Copy AltiCtrl.ocx file from the AltiAgent API directory to the Windows system32 directory.
3. Bring up the 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.

AltiAgent 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. Right-click 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. Please 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 AltiCtrlinto the project. Click OK to 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.

4 AltiAgent ActiveX Programmer’s Guide
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, BSTR
szCallerID, BSTR szCallerName, BSTR szCallDNIS, BSTR szWorkgroup,
BSTR pszDateTime, BSTR pszDuration)

AltiAgent ActiveX Programmer’s Guide 5
Parameters
ulSessionID
uStatus
szCallerID
szCallerName
szCallDNIS
pszDateTime
pszDuration
= Session ID
= Call Status
= Caller ID
= Caller Name
= DNIS
= Call start date and time
= Conversation duration

6 AltiAgent ActiveX Programmer’s Guide
Remark
Call status value:
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
LINECALLSTATE_MONITORSIRENT
LINECALLSTATE_CALLBARGEIN
LINECALLSTATE_XFER_RINGBACK
LINECALLSTATE_XFER_WAITFORONHOOK
LINECALLSTATE_DUMMYRING
LINECALLSTATE_FORWARDRING
LINECALLSTATE_DATALOAD
LINECALLSTATE_RECORD
LINECALLSTATE_APC
LINECALLSTATE_SUPERVISE_COACH
LINECALLSTATE_LINE_PARK
LINECALLSTATE_RMT_OFFLINE
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

AltiAgent ActiveX Programmer’s Guide 7
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 defined by user.
VC++ Syntax
BOOL SetUserData(int SessionID , BSTR 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. It is only used for trunk line calls.
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
CComBSTR bstrdata = _T("user data");
m_altictrl. SetUserData (ulSessionID, bstrData);
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
BSTR GetUserData(int SessionID)

8 AltiAgent ActiveX Programmer’s Guide
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
CComBSTR bstrData;
bstrData = 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, BSTR 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.

AltiAgent ActiveX Programmer’s Guide 9
VC++ Example
CComBSTR bstrData = _T("ivr data");
m_altictrl. SetURLData (ulSessionID, bstrdata);
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
BSTR 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
CComBSTR bstrData;
bstrData = m_altictrl.GetIVRData (ulSessionID);
VB Example
Dim data As String
Data = AltiCtrl1.GetIVRData(ulSessionID)

10 AltiAgent ActiveX Programmer’s Guide
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 the user application can know where
this call comes from.
Note
SetURLData is a reserved API.
VC++ Syntax
BOOL SetURLData(int SessionID,BSTR 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
CComBSTR bstrData = _T("url data");
m_altictrl. SetURLData (ulSessionID, bstrData);
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
BSTR GetURLData(int SessionID)

AltiAgent ActiveX Programmer’s Guide 11
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
CComBSTR bstrData;
bstrData = 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 ,BSTR 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
CComBSTR bstrName = _T("Tom");
m_altictrl.SetCallerName(ulSessionID, bstrName);

12 AltiAgent ActiveX Programmer’s Guide
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
BSTR GetExtNumber()
VB++ Syntax
object.GetExtNumber()
Return type
String extension number for the AltiAgent login is 256 bytes.
VC++ Example
CComBSTR bstrData = m_altictrl.GetExtNumber();
VB Example
Dim data as String
data = AltiCtrl1.GetExtNumber()
MakeCall
Description
Make a call through AltiAgent.
VC++ Syntax
long MakeCall(BSTR bstrDialNumber);
VB++ Syntax
object.MakeCall(string)
Parameters
bstrDialNumber [In]: Destination telephone number, less than 32
digits
Return type
0 - Make call command is sent successfully

AltiAgent ActiveX Programmer’s Guide 13
1 - Unknown error occurs
2 - Disconnect AltiAgent
999 - Exception occurred
VC++ Example
BOOL bstart= m_altictrl. MakeCall(L"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
BSTR GetTrunkAccessCode ();
VB++ Syntax
object. GetTrunkAccessCode()
Return type
Default trunk access code set in AltiAgent
VC++ Example
CComBSTR bstrTrunkAccess= m_altictrl. GetTrunkAccessCode ();
VB Example
Dim data As String
data = AltiCtrl1.GetIVRData(ulSessionID)
Note: The ctrl will show a window in the client application. To hide the window, use the following
code
VC++ Example
m_altictrl.ShowWindow(SW_HIDE);
VB Sample
AltiCtrl1.Visible = TRUE
DropCall
Description
Drops the current call.

14 AltiAgent ActiveX Programmer’s Guide
VC++ Syntax
long DropCall();
VB++ Syntax
long DropCall();
Return type
0 - Drop call command is sent successfully
!= 0 - Unknown error occurs
VC++ Example
long result = m_altictrl.DropCall();
VB Example
Dim data As Long
data = AltiCtrl1.DropCall()
SetBK
Description
Sets the background color of AltiCtrl.
VC++ Syntax
long SetBk(short sRed, short sGreen, short sBlue)
VB++ Syntax
long SetBk(short sRed, short sGreen, short sBlue)
Parameters
sRed[in]:RGB's red value of the background color of AltiCtrl.
sGreen[in]: RGB's green value of the background color of AltiCtrl.
sBlue[in]: RGB's blue value of the background color of AltiCtrl.
VC++ Example
m_altictrl.SetBk (128, 101, 122);
VB Example
AltiCtrl1.SetBk 128, 101, 122