Eyeball Messenger SDK V10.0 Developer Reference Guide

Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved.
Eyeball Messenger SDK v10.0
Developer Reference Guide
Last Modified: June 2014

1. Messenger SDK Introduction
Introduction
Eyeball Messenger Software Development Kit (SDK) provides tools to application developers that allow
integration of live video communications features into new or existing applications and services.
Developers can use Eyeball Messenger SDK to create a custom client application with peer-to-peer
audio/video communications, text messaging and presence/availability management. These video-
enabled applications communicate with server components to seamlessly deliver interactive, high-quality
video to users. Eyeball Messenger SDK incorporates Eyeball’s patented AnyFirewallTM and
AnyBandwidthTM technologies to ensure 100% connectivity and the best possible call quality.
Eyeball Messenger SDK provides a powerful solution for developers to integrate the following features
into their products quickly and easily:
 Interactive audio communications
 Interactive peer-to-peer video communications
 Instant text messaging, online presence detection and contact list management
These features can be applied to applications and services such as on-line customer support, web
communities, distributed games, distance education and entertainment.

Benefits of Eyeball Messenger SDK
Some of the benefits of Eyeball Messenger SDK include:
 Guaranteed Best Video Quality
Internet video quality is affected by unpredictable bandwidth, packet loss, latency, jitter and
CPU heterogeneity. Eyeball Messenger SDK uses Eyeball’s patented AnyBandwidthTM
technology to guarantee the best possible video quality over any Internet connection and on
any device.
 Seamless Firewall Interoperability
Firewalls and modems can inadvertently block video calls, resulting in frustration, lost
productivity and missed revenue opportunities. Eyeball’s patented and patented AnyFirewall™
technology ensures seamless video delivery between any combinations of standard firewalls
and modems without compromising firewall security. This includes TURN compliant relay using
UDP, TCP or HTTP proxy tunneling.
 Scalable Peer-to-Peer Architecture
Sending audio and video data through a central relay server consumes costly server hardware
and bandwidth resources, and reduces video quality. Eyeball’s server solutions are based on a
peer-to-peer architecture in which data is sent directly from one client computer to another. As
a result, Eyeball can scale service providers to millions of users with minimal operational costs
and maximum video quality.
 Embedded Video Support
Eyeball Messenger SDK allows application developers to implement video communications as
either a standalone client or an embedded component in an application. When embedded, the
video client is sent to a user seamlessly as part of an application. This eliminates the need for
users to install a separate video client and allows developers to update their application without
the installation of new video client software.
 Multiple SIP Accounts
Application developers and users can register multiple SIP accounts, with multiple proxy
servers.

Contents of Eyeball Messenger SDK
Eyeball Messenger SDK v10.0 consists of:
 Eyeball Messenger SDK v10.0 ActiveX for Windows,
 Eyeball Messenger SDK v10.0 Java Library for Android,
 Eyeball Messenger SDK v10.0 C++ Library for iOS and Mac,
 Source code for sample applications for each platform.
How to use this Reference Guide
This guide includes general implementation guidelines and examples and more detailed listings of
properties, methods, notification events and error handling.
Section 2 How applications and services developed on Eyeball Messenger SDK work
Section 3 Supported Platforms
Section 4 Supported Standards
Section 5 How to use Eyeball Messenger SDK
Sections 6 – 11 Listing of properties, methods, notification events and error handling
Section 12 Common error codes
Section 13 Legal and contact information

1.1. Benefits of Eyeball Messenger SDK
Benefits of Eyeball Messenger SDK
Some of the benefits of Eyeball Messenger SDK include:
 Guaranteed Best Video Quality
Internet video quality is affected by unpredictable bandwidth, packet loss, latency, jitter and
CPU heterogeneity. Eyeball Messenger SDK uses Eyeball’s patented AnyBandwidthTM
technology to guarantee the best possible video quality over any Internet connection and on
any device.
 Seamless Firewall Interoperability
Firewalls and modems can inadvertently block video calls, resulting in frustration, lost
productivity and missed revenue opportunities. Eyeball’s patented and patented AnyFirewall™
technology ensures seamless video delivery between any combinations of standard firewalls
and modems without compromising firewall security. This includes TURN compliant relay using
UDP, TCP or HTTP proxy tunneling.
 Scalable Peer-to-Peer Architecture
Sending audio and video data through a central relay server consumes costly server hardware
and bandwidth resources, and reduces video quality. Eyeball’s server solutions are based on a
peer-to-peer architecture in which data is sent directly from one client computer to another. As
a result, Eyeball can scale service providers to millions of users with minimal operational costs
and maximum video quality.

 Embedded Video Support
Eyeball Messenger SDK allows application developers to implement video communications as
either a standalone client or an embedded component in an application. When embedded, the
video client is sent to a user seamlessly as part of an application. This eliminates the need for
users to install a separate video client and allows developers to update their application without
the installation of new video client software.
 Multiple SIP Accounts
Application developers and users can register multiple SIP accounts, with multiple proxy
servers.

1.2. Contents of Eyeball Messenger SDK
Contents of Eyeball Messenger SDK
Eyeball Messenger SDK v10.0 consists of:
 Eyeball Messenger SDK v10.0 ActiveX for Windows,
 Eyeball Messenger SDK v10.0 Java Library for Android,
 Eyeball Messenger SDK v10.0 C++ Library for iOS and Mac,
 Source code for sample applications for each platform.

1.3. Messenger SDK Supported Features
Supported Features
Eyeball Messenger SDK v10.0 enables rapid development of customized applications and services that
support real-time audio/video communications based on Session Initiation Protocol (SIP 2.0, RFC 3261).
This SDK provides a powerful solution for developers to integrate standards-based audio/video
communications features and instant messaging into their products quickly and easily.
Eyeball Messenger SDK v10.0 supports the following features:
Feature Windows Android iOS OSX
Full SIP 2.0 (RFC 3261) compliance √ √ √ √
Send/receive audio/video calls (using soft-phones, standard phones
(POTS), IP-phones, and video-phones)
√ √ √ √
Multiple concurrent calls √ √ √ √
Audio and video conferencing √ NCS* NCS* NCS*
Advanced call features (call forward, call hold, and call transfer) √ √ √ √
Call history (incoming and outgoing) √ √ √ √
Proxy/WWW authentication √ √ √ √
Multiple proxy authentication √ √ √ √
STUN firewall detection √ √ √ √
Smart NAT traversal using AnyFirewall™ Engine, including TURN
compliant call relay using UDP, TCP
√ √ √ √
HTTP proxy tunneling with support for basic, NTLM v1, and NTLM v2
authentication
√ √ √ √
G.711 (A-law, µ-law), G.729 Annex A, and Speex audio codecs √ √ √ √
GSM, iLBC, Polycom® Siren™ (G722.1C, 24 kHz, and 48 kHz) audio
codecs
√ NCS* NCS* NCS*
H264 (main profile) video codec √ √ √ √
H.263, H.263+, and EyeStream video codecs √ NCS* NCS* NCS*
Acoustic echo cancellation (AEC) and auto gain control (AGC) √ √ √ √
Adaptive jitter buffering √ √ √ √

Early media handling √ √ √ √
DTMF digits (for PBX calls and Touch Tone services) using RFC 2833
(RTP Payload), RFC 2976 (SIP INFO), or inband
√ √ √ √
Snapshot of local or remote video √ NCS* NCS* NCS*
DNS SRV lookup for SIP, STUN, and XMPP servers √ √ √ √
Multiple SIP accounts for registration with multiple SIP proxies at the
same time
√ √ √ √
Buddy list/block list management √ √ √ √
SIP Forking √ √ √ √
Contact groups √ √ √ √
Display name √ √ √ √
Presence update √ √ √ √
Standard and custom user state/status √ √ √ √
Typing indication √ √ √ √
Multiple user resources √ √ √ √
User profile √ √ √ √
Text chat √ √ √ √
Multiparty text chat √ √ √ √
Offline messages √ √ √ √
File transfer √ √ NA √
Call hold/un-hold √ √ √ √
*NCS (Not Currently Supported) features can in many cases be implemented within short
time frames
*NA features are not applicable to the stated platform

1.4. Messenger SDK Supported
Platforms
Supported Platforms
Eyeball Messenger SDK supports today’s most popular platforms and programming languages, making
service development flexible, and fast.
Figure 1: Eyeball Messenger SDK allows development of stand-alone and web-based applications and
services using languages such as C++, HTML and JavaScript, and Visual Basic.

1.5. Messenger SDK: How to use this
Reference Guide
How to use this Reference Guide
This guide includes general implementation guidelines and examples and more detailed listings of
properties, methods, notification events and error handling.
Section 2 How applications and services developed on Eyeball Messenger SDK work
Section 3 Supported Platforms
Section 4 Supported Standards
Section 5 How to use Eyeball Messenger SDK
Sections 6 – 11 Listing of properties, methods, notification events and error handling
Section 12 Common error codes
Section 13 Legal and contact information

2. Messenger SDK Application and
Service Architecture
Application and Service Architecture
Using Eyeball Messenger SDK, application developers can implement text communications as either a
standalone client or an embedded component in an application, service or website.

Figure 2: Applications and services based on Eyeball Messenger SDK
Figure 2 shows details of Eyeball Messenger SDK architecture and the possible applications that can be
built with it. Software developers can implement new applications, services or websites that will have
Eyeball Messenger SDK components embedded in them. They may be stand-alone applications that
execute in Microsoft Windows or other operating systems, and web-based applications and services that
can be accessed using a web browser such as Internet Explorer and others.
In order for these applications and services to provide interactive chat communication capabilities, the
embedded Eyeball Messenger SDK components need to communicate with the respective standard-
compliant servers. For example a XMPP server for instant messaging such as Eyeball XMPP server.
For the best possible firewall traversal solution, Eyeball’s AnyFirewall™ Server is recommended.

3. Messenger SDK Supported Platforms
Product
iOS OS X Windows Android
Messenger SDK Messenger SDK Messenger SDK Messenger SDK
CPU
Operating System:
iOS 5.0 or later
Processor Type:
Apple A5
Processor Core:
Dual Core
AMU Data Bus: 32
bit
CPU Clock: 1GHz
Flash Memory
Capacity: 16 to 64
GB
Operating System:
OS X 10.6.6 or later
Processor Type:
Apple A5
Processor Core: Dual
Core
AMU Data Bus: 32 bit
CPU Clock: 1GHz
Flash Memory
Capacity: 16 to 64 GB
Operating System:
Win 98, XP, 7, Vista
Processor Type:
AMD64, EM64T
AMU Data Bus:
32/64 bit
CPU Clock: 500
MHz (min.)
RAM: 256 MB (min.)
Operating System:
Android 2.3 or later
Chipset: TI OMAP 4430
Processor Type: Tegra 2
Processor Core: Dual
Core
AMU Data Bus: 32 bit
CPU Clock: 1GHz
Flash Memory Capacity:
16 GB
Packaging
.ipa
(iOS App
Archive)
.a
(Static
Library
for
iOS)
.dylib
(Dynamic
Library)
.msi
(installer
package),
.exe
(executable)
.msi,
.exe
.apk
(Android
pack)
.so
(Shared
object), .jar
(Java
package)
APIs/
Supported
Languages
C++ C++
C++, Obj.
C++
C++, Obj.
C++
C, C++, C#,
VB.Net
C,
C++,
C#,
VB.Net
Java C++
IDEs
Xcode v4.2
or later
Xcode
v4.2 or
later
Xcode v4.2
or later
Xcode
v4.2 or
later
Visual
Studio 2005
& later
Visual
Studio
2005 &
later
Eclipse,
Netbeans
Eclipse,
Netbeans
Browser
(OS
support)
Safari Safari
IE, Chrome, Safari,
Firefox, Opera
Chrome, Firefox, Opera
Browser
(MSDK
Support)
n/a n/a n/a
IE 8.0
or later
n/a n/a

3.1. Messenger SDK for Windows
Windows
System Requirements
Operating System:
Vista, Win 7, Win 8
Hardware Requirements:
Computers
Developer Platforms
Programming Languages:
C/C++, C#, HTML and Javascript
Developer Tools:
Visual Studio 2005 or later
Other software:
DirectX 8.1

Programming Conventions
In this document, the phrase current user refers to the local user, as opposed to the remote user.
We use the following conventions to define a variable’s data type:
 Variable name starting with ‘n’ such as nFileId refers to an Integer data type
 Variable name starting with ‘s’ such as sUserID refers to a String data type
 Variable name starting with ‘b’ such as bAccept refers to a Boolean data type
 Variable name starting with ‘a’ such as aContactList refers to a VB array data type. This is a one-
dimensional array. Storing two-dimensional information is simply done by concatenating rows to
each other, forming a one-dimensional array.
All strings are case-sensitive unless specified otherwise.
The calling convention for properties follows this format:
// Set keep alive period
XmppCommCtl.KeepAlivePeriod = 30;
// Retrieve the keep alive period
int nKeepAlivePeriod = XmppCommCtl.KeepAlivePeriod;

3.2. Messenger SDK for Android
Android
System Requirements
Operating System:
Android 2.3 or later
Hardware requirements:
Android phone/tablet
Developer Platforms
Java
Developer Tools:
Android SDK 2.3.3 or later
Please see Programming Conventions in Section 3.1. Messenger SDK for Windows.
The methods and properties are static and implemented in the XmppJniWrapper and JSipJniWrapper.

Unless otherwise specified, the calling convention for properties follows this format:
// Select a line
SipJniWrapper.SipCommPutSelectedLine(1);
// Retrieve the currently selected line
int nSelectedLine = SipJniWrapper.SipCommGetSelectedLine();
For methods which return a VB array on Windows, return a string array to Android using this format:
String[] stats = SipJniWrapper.SipCommGetAudioReceiverStat();
For notification events which provide elements in a VB array on Windows, the elements are provided as
arguments on Android using this format:
SipCommOnRegisterResponse(int nResponse, int nStatusCode, String sReason, int nProxy,
int nAccnt){}

3.3. Messenger SDK for iOS, Mac
iOS, Mac
System Requirements
Operating System:
iOS 5.0 or later for iOS and Mac OS X 10.6.6 or later for Mac
Hardware Requirements:
iPad, Mac PCs, audio device, camera for video call
Developer Platforms
C++, Objective C++
Developer Tools:
Xcode
Please see Programming Conventions in Section 3.1. Messenger SDK for Windows.

The methods and properties are defined in class CSipComm in file MediSession.h. To access these
methods, an object of CSipComm needs to be created. Please see 5.1 Creating XMPPComm and
SIPComm objects.
Unless otherwise specified, the calling convention for properties follows this format:
// Select a line
sipAgent->sipComm->put_SelectedLine(1);
// Retrieve the currently selected line
int nSelectedLine;
sipAgent->sipComm->get_SelectedLine(&nSelectedLine);
For methods which return a string on Windows, the string must be passed by reference in iOS and Mac
OS X using this format:
string sDisplayName;
sipAgent->sipComm->GetDisplayName(&sDisplayName);
For methods which return a VB array on Windows, a vector must be passed by reference in iOS and Mac
OS X using this format:
vector<string> stats;
sipAgent->sipComm->GetAudioReceiverStat(&stats);
For notification events which provide elements in a VB array on Windows, the elements are provided as
arguments in iOS and Mac OS X using this format:
OnRegisterResponse(int nResponse, int nStatusCode, const string &sReason, int nProxy,
int nAccnt){}

4. Messenger SDK Supported Standards
Supported Standards
The supported standard RFC & XEPs are as follows:
RFC
 RFC 3920: XMPP Core
 RFC 3921: XMPP IM
 RFC 3261: SIP
 RFC 3489: STUN
 RFC 5766: TURN
 RFC 5245: ICE
XEP
 XEP 0030: Service Discovery
 XEP 0077: In-Band Registration
 XEP 0078: Non-SASL Authentication
 XEP 0086: Error Condition Mappings
 XEP 0115: Entity Capabilities
 XEP 0013: Flexible Offline Message Retrieval
 XEP 0049: Private XML Storage
 XEP 0084: User Avatar
 XEP-0085: Chat State Notifications
 XEP-0045: Multi-User Chat
 XEP-0136: Message Archiving

5. Using Eyeball Messenger SDK
Using Eyeball Messenger SDK
Eyeball Messenger SDK consists of libraries of ActiveX controls (Windows)/Java (Android)/C++ (iOS) that
provide programmers with a high-level interface to the main features and functions of Eyeball Messenger.
The methods can be split into two subgroups:
 XMPP Communicator control: Supports contact list, presence detection, instant text messaging
and file transfer.
 SIP Communicator control: Supports video calls between two parties, multiple SIP accounts,
advanced telephony features (multiple lines, hold, forward, caller ID, etc.), DTMF, media settings,
device selection and volume adjustment.
In addition, there are controls available to display and handle video windows (for SIP video calls, used
together with the SIP Communicator control), audio device detection and federated IM, i.e.,
interoperability with other instant messaging services like MSN, Yahoo!, AOL, Google Talk, or ICQ.
In this section, we present Eyeball Messenger SDK from a web-programmer’s point of view. However,
programmers using other languages such as C++ and Visual Basic will also get a clear understanding of
the supported features and functionalities.

5.1. Messenger SDK: Creating
XMPPComm and SIPComm objects
Creating XMPPComm and SIPComm
objects
The following HTML code shows how to embed the ActiveX control objects into a web page:
Windows:
<OBJECT
id="XMPPCommCtl"
classid="CLSID: 690BC7EC-8614-415c-A59B-2EAFCBF462A8">
</OBJECT>
<OBJECT
id="SipCommCtl"
classid="CLSID: 968E1865-05A8-41dd-95B5-7D45B9701A57">
</OBJECT>
<OBJECT
id="VideoWindowCtl"
classid="CLSID: 0504639F-FBD4-4272-B232-AB9B21305618">
<param name=”IsWndless” value=true>
</OBJECT>
Android:
public class Messenger extends Activity implements SipEventHandler, XmppEventHandler{
public void onCreate(Bundle savedInstanceState){
SipJniWrapper.AudioInit((Activity)this);
SipJniWrapper.SetSipEventHandler(this);
XmppJniWrapper.SetXmppEventHandler(this);

SipJniWrapper.SipCommInit();
XmppJniWrapper.XmppCommInit();
}
}
iOS, Mac OS X:
class XmppAgent: public CXmppCommEventHandler{
public:
CXmppComm *xmppComm;
XmppAgent(){
xmppComm = new CXmppComm(this);
}
class SipAgent : public CSipCommEventHandler {
public:
CSipComm *sipComm;
SipAgent(){
sipComm = new CSipComm(this);
}
XmppAgent *xmppAgent = new XmppAgent();
SipAgent *sipAgent = new SipAgent();

5.2. Messenger SDK: Using the Features
and Functions
Using the Features and Functions
Some of the main features and functions of Eyeball Messenger SDK are described in the following
sections:
 5.2.1. Messenger SDK: Using the XMPP Communicator Control
 5.2.2. Messenger SDK: Using the SIP Communicator Control
 5.2.3. Messenger SDK: Use Multiple SIP Accounts
 5.2.4. Messenger SDK: Holding a Conference Call

5.2.1. Messenger SDK: Using the XMPP
Communicator Control
Using the XMPP Communicator Control
Contact List
The control allows contacts to be programmatically added and deleted.
Adding a new user to the Contact List
Windows:
XMPPCommCtl.AddContact("UserID", ”FirstName”, ”LastName”, ”DisplayName”,”GroupName”);
Android:
xmppJniWrapper.XMPPCommAddContact("UserID", ”FirstName”, ”LastName”, ”DisplayName”,
”GroupName”);
iOS, Mac OS X:
xmppAgent->xmppComm->AddContact("UserID", ”FirstName”, ”LastName”, ”DisplayName”,
”GroupName”);
Deleting a user from the Contact List
Windows:

XMPPCommCtl.RemoveContact("UserID");
Android:
xmppJniWrapper.XMPPCommRemoveContact("UserID");
iOS, Mac OS X:
xmppAgent->xmppComm->RemoveContact("UserID");
Detecting a user's status
Windows:
sStatus = XMPPCommCtl.GetPresenceStatus("UserID");
Android:
sStatus = XmppJniWrapper.XMPPCommGetPresenceStatus("UserID");
iOS, Mac OS X:
string sStatus;
xmppAgent->xmppComm->GetPresenceStatus(&sStatus);
Retrieving a copy of the current Contact List (to support operations such as printing or iterating through
the list)
Windows:
aContactList = XMPPCommCtl.GetContactList();
Android:
aContactList = XmppJniWrapper.XMPPCommGetContactList();
iOS, Mac OS X:
std::vector <std::string> vs;
xmppAgent->xmppComm->GetContactList(&vs);

Instant Messaging
Sending a text message to another online user
Windows:
XMPPCommCtl.SendChatMessage(nSessionId,"UserID", "hello");
Android:
xmppJniWrapper.XMPPCommSendChatMessage(nSessionId,"UserID", "hello");
iOS, Mac OS X:
xmppAgent->xmppComm->SendChatMessage(nSessionId,"UserID", "hello");
File Transfer
Sending a file to another online user
Windows:
FileId = XMPPCommCtl.SendFile("UserID", "testfile.txt");
iOS, Mac OS X:
xmppAgent->xmppComm->SendFile("UserID", "testfile.txt");
Android:
FileId = XmppJniWrapper.XmppCommSendFile("UserID", "testfile.txt");
This is not applicable to the iOS environment.
Accepting a file from another user
Windows:
XMPPCommCtl.AcceptFileTransfer(FileId, “testfile.txt”, true);

iOS, Mac OS X:
xmppAgent->xmppComm->AcceptFileTransfer(FileId, “testfile.txt”, true);
Android:
JNIWraper.XmppCommAcceptFileTransfer(FileId, “testfile.txt”, true);
This is not applicable to the iOS environment.
Multiple files can be sent and received simultaneously.

5.2.2. Messenger SDK: Using the SIP
Communicator Control
Using the SIP Communicator Control
This control supports peer-to-peer audio/video data-transport. Eyeball Messenger SDK supports the
multiple-line concept (like multi-line PBX phones), enabling the following features:
 Identifying each call using a separate line while in multiple concurrent calls
 Choosing a specific available line to make the next call
In addition, Eyeball Messenger SDK supports multiple SIP accounts, enabling the following features:
 Registering multiple SIP accounts with multiple SIP proxy servers
 Making simultaneous calls on different accounts, switching between these calls using Hold/Un-
hold
 Enabling conferencing on some SIP accounts while making one-to-one calls on others
Call User
Sending an audio/video call request to a user
Windows:
SipCommCtl.Call(sTargetURI, sDomain, bAnonoumous, bPhone, bConf);
Android:
SipJniWrapper.SipCommCall(sTargetURI, sDomain, bAnonoumous, bPhone, bConf);

iOS, Mac OS X:
sipAgent->sipComm->Call(sCallURI, sDomain, bAnonoumous, bPhone, bConf);
The callee will receive an OnCallRequest event containing the incoming line number and caller
information.
Answering an audio/video call
Windows:
SipCommCtl.RespondCall(nLine, true, bAccept, bConf);
Android:
SipJniWrapper.SipCommRespondCall(nLine, true, bAccept, bConf);
iOS, Mac OS X:
sipAgent->sipComm->RespondCall(iLine, bAccept, bConf);
Ending a specific call
Windows:
SipCommCtl.EndCall(false);
Android:
SipJniWrapper.SipCommEndCall(false);
iOS, Mac OS X:
sipAgent->sipComm->EndCall(false);
Send DTMF

Sending DTMF tones is required for PBX calls and Touch Tone services.
Sending DTMF tones
iOS, Mac OS X:
sipAgent->sipComm->EndCall(false);
The digit “5” is sent as a DTMF signal.
Hold Call
Holding the current call
Windows:
SipCommCtl.SelectedLine = 1;
SipCommCtl.HoldLine = true;
SipCommCtl.RespondCall(2, true);
Android:
SipJniWrapper.SipCommPutSelectedLine(nLine);
SipJniWrapper.SipCommPutHoldLine(bHold);
iOS, Mac OS X:
sipAgent->sipComm->put_SelectedLine(nLine);
sipAgent->sipComm->put_HoldLine(bHold);
Switching back to the first call

Windows:
SipCommCtl.HoldLine = true;
SipCommCtl.HoldLine = false;
Android:
SipJniWrapper.SipCommPutSelectedLine(nLine);
SipJniWrapper.SipCommPutHoldLine(bHold);
iOS, Mac OS X:
sipAgent->sipComm->put_SelectedLine(nLine);
sipAgent->sipComm->put_HoldLine(bHold);

5.2.3. Messenger SDK: Use Multiple SIP
Accounts
Use Multiple SIP Accounts
Eyeball Messenger SDK v8.1 enables a user to create multiple SIP accounts on the same SipComm
control. When working on multiple SIP accounts, the user usually needs to set a SIP account to be active,
before calling methods on that account. The only exception to this is when calling methods/properties in
response to a notification event, or when using hold/un-hold, where the SDK will identify the
corresponding SIP account from the passed parameters (i.e., Line, TargetURI). The following example
shows how to create and manipulate a SIP account.
SipCommCtl.SelectedSipAccount = 1;
//The following methods are called on SIP Account 1
SipCommCtl.SetProxyServer(index, proxy, port);
...
SipCommCtl.Register();
SipCommCtl.Call(user, true, false);
SipCommCtl.EndCall();
//The following methods are called on SIP Account 2
SipCommCtl.SetProxyServer(index, proxy, port);
...
SipCommCtl.Call(user, true, false);
SipCommCtl.EndCall();
Later on, if the user needs to hold/un-hold a call or reply to a notification event, they do not need to set a
SIP account. For example:
SipCommCtl.Call(URI); //call account 1

SipCommCtl.Call(URI); //call account 2
//the SDK will call the following functions on the
//account associated with by the line or URI.
SipCommCtl.RespondCall(nLine);
SipCommCtl.RespondCall(nLine);
SipCommCtl.RespondData(sTargetURI);
SipCommCtl.HoldLine = true; //holds SelectedLine
Some methods affect all SIP accounts and/or retrieve information that is common between all SIP
accounts. Such methods do not need the SIP account to be set before they are used. For example:
SipCommCtl.GetCallHistory();
See Section 6 SIP Communicator for more information on methods/properties needed to configure SIP
accounts.

5.2.4. Messenger SDK: Holding a
Conference Call
Holding a Conference Call
In this section, we describe how to hold a conference call using Eyeball Messenger SDK APIs. We
explain the APIs with a scenario where the conference is initiated by the host H. First of all, H makes a
conference call to participant A. Later on, H accepts a call from B and puts B in a conference with A (i.e.,
H, A, and B are in a conference). Finally, H holds the conference and makes a one-to-one call to C. The
line numbers used for conversing with A, B, and C are assumed to be L1, L2, and L3 respectively. Table
1 shows the sequence of API calls made by H in order to simulate the scenario described above.
Call Sequence API Calls by Host H Comments
Host H makes a
conference call
to A
SelectedLine = L1
Call (“A”, false,
false, true)
H can add participants later on in this conference call. A
receives OnMoveToConference(true), and
OnConferenceMemberListUpdate() events.
H accepts a call
from B
HoldConference =
true
RespondCall(L2,
true, false)
H puts the conference with A on hold and accepts the call
from B as a one-to-one call.
H adds B in the
conference
SelectedLine = L2
ConferenceLine =
true
HoldConference =
false
At this point H, A, and B is in a conference.
OnMoveToConference(true) event is fired for B, and
OnConferenceMemberListUpdate() event is fired for both A
and B.
H makes a one-
to-one call to C
HoldConference =
true
SelectedLine = L3
Call(“C”, false,
false, false)
H will be in a one-to-one call with C. A and B will be able to
exchange media among themselves. However, H won’t send
or receive any media from A or B.
Table 1: Holding a Conference Call using Eyeball Messenger SDK APIs

5.3. Messenger SDK: Handling Event
Notifications
Handling Event Notifications
The applications send several event notifications to the application running on Eyeball Messenger SDK.
The application needs to handle these events as necessary. For example, XMPP control will send event
notifications such as:
 Text messages
 File transfer requests
 Contact list updates
Most of the events are fired with relevant information as parameters. The following code shows how the
OnChatMessage event can be handled.
Windows:
<SCRIPT language=JScript for=XMPPCommCtl
event=OnChatMessage(aMessage)>XMPPCommCtl_OnChatMessage(aMessage);
</SCRIPT>
function XMPPCommCtl_OnChatMessage(aMessage)
{
var aMsg = aMessage.toArray();
var sSender = aMsg[1];
var sText = aMsg[2];
var nAccnt = aMsg[3];
alert(sSender + “: ” + sText);
}
Android:
void Fire_XMPPCommOnChatMessage(String sSender, String sText, int nAccnt)
{
//sSender contains the name of the sender

//sText conatins message
//nAccnt contains the id of the SIP account
}
iOS, Mac:
void Fire_OnChatMessage(int nSessionID, const std::string &strSender, const
std::string &strMsg, const std::string &strHtml)
{
NSString* sender = [NSString stringWithUTF8String:strSender.c_str()];
NSString* msg = [NSString stringWithUTF8String:strMsg.c_str()];
NSLog(@"%@: %@", sender, msg);
}
SipEventHandler will send event notifications such as:
 Incoming audio/video call request
 Audio/video call response
 Modified audio/video call parameters
The SIP account which generated the event is passed as the last parameter. It is only provided as a
reference.
The following code can handle the OnCallRequest event:
Windows:
<SCRIPT language=JScript for= SipCommCtl event= OnCallRequest(aRequestInfo)>
return SipCommCtl_OnCallRequest(aRequestInfo)
</SCRIPT>
function SipCommCtl_OnCallRequest(aRequestInfo)
{
var aInfo = aRequestInfo.toArray();
var nLine = aInfo[0];
var sDisplayName = aInfo[1];
var sURI = aInfo[2];
var bAudioVideo = aInfo[3];
alert(“Call received on line ” + nLine + “ from ” + sDisplayName + “(“ + sURI + “)”);
}
Android:
void OnCallRequest(int i_line, String str_display_name, String str_target_uri, boolean
b_video_call, int i_spit_rating, int i_accnt, String str_reason)
{

//Handle Call Request
}
iOS, Mac:
void OnCallRequest(int i_line,
const std::string &str_display_name,
const std::string &str_target_uri,
bool b_video_call, int i_spit_rating,
int i_accnt, const std::string &str_reason)
{
//Handle Call Request
}
Notice that none of the methods called in response to notification events require setting a SIP account.
The SDK will use the information passed to it, i.e., nLine, sTargetURI, to figure out which SIP account is
responsible for handling this event.

5.4. Messenger SDK: Sample Application
(Windows) - E-Commerce Web Site
Sample Application (Windows) - E-
Commerce Web Site
The following example shows how easy it is to integrate Eyeball Messenger SDK into a web site. The
demo application implements a one-click connection to a company's customer representative.
Customer Support Page
Figure 3: Interface for a customer support web page using Eyeball Messenger SDK.

Suppose that on the "Contact Us" page of the company's web site, there is a SipCommCtl control and two
buttons: one to start the video call, and the other to end the call, as in Figure 3. The user can click the
start button and instantly begin chatting with the customer representative, who is using an Eyeball
Messenger client.
<INPUT type=text name=TextUserID>
<INPUT type=password name=TextPassword>
<INPUT type=button value="Start Call" name=BtnStart>
<INPUT type=button value="End Call" name=BtnEnd>
// Handle a click on the "Start Call" button
function BtnStart_OnClick()
{
SipCommCtl.SetAccount(0, TextUserID.value, TextUserID.value, TextPassword.value);
SipCommCtl.EnableRegistration(0, true)
SipCommCtl.Call("CustomerCare@domain.com", false, false);
}
// Handle a click on the "End Call" button
function BtnEnd_OnClick()
{
SipCommCtl.EndCall(false);
SipCommCtl.Logout();
}

6. Messenger SDK: SIP Communicator
SIP Communicator
For the list of features supported by the SIP Communicator control, please see the complete features
table on Section 1.3. Messenger SDK Supported Features.
The SIP Communicator control uses the concept of line as follows:
 An application program may be a single-line application or a multi-line application, and for multi-
line applications, a programmer can choose the number of lines available for end-users.
 Each line is identified using a number. For example, if an application has 3 lines, the lines will be
denoted as lines 0, 1 and 2.
 When an incoming call is received, Eyeball Messenger SDK assigns the first available line to the
call. If all lines are busy, the caller will receive “Busy Here” and the call will not be established.
The SIP Communicator control uses the concept of multiple SIP accounts:
 An application program may register multiple user accounts with multiple SIP proxy servers.
 Each SIP account is identified using a number provided by the application programmer.
 A SIP account could have multiple call lines, but not the reverse. A call line already used by one
SIP account cannot be re-used by another SIP account.
The following HTML code embeds the SipCommCtl ActiveX object into a web page:
<OBJECT
id="SipCommCtl"
classid="CLSID:968E1865-05A8-41dd-95B5-7D45B9701A58">
</OBJECT>
The SipCommCtl object supports one single interface ISipComm. Properties, methods, and events of the
control are described in the next section.
Many methods or properties will have one of the following descriptions:

 “This method/property is called on the SelectedSipAccount.” This means that the user must call
SipCommCtl.SelectedSipAccount = nAccnt for the method to be called on the SIP account
specified by nAccnt. Any changes it makes (information it retrieves) will only affect (belong to) this
account. These methods will not have any effect if an invalid SIP account is selected.
 “This method/property is not SIP account specific.” Such methods are invoked on the
SelectedSipAccount, but the changes they make will affect all SIP accounts (e.g., FrameRate),
and the information they retrieve is information that is common to all SIP accounts (e.g.,
GetCallHistory).
 “This method/property is called on the SIP account associated with nLine/SelectedLine.” No SIP
account needs to be set. Eyeball Messenger SDK will use nLine/SelectedLine to identify which
SIP account to use.
 “This method/property is called on the SIP account associated with sTargetURI.” No SIPaccount
needs to be set. Eyeball Messenger SDK will use sTargetURI to identify which SIPaccount to
use.

6.1. Messenger SDK Properties
Properties
AudioCaptureDevice
This sets a preferred audio capture device by the index or retrieves the index of the device in use as an
Integer. The index is zero-based. This value can be changed during a call.
This property is not SIP account specific, and hence, affects all SIP accounts
This is not applicable to Android or iOS environments.
AudioCodecs
This sets or retrieves preferred audio codecs. Currently, Polycom® Siren™ (G722.1C, 24kHz, 48kHz),
GSM, G.711 (A-law, µ-law), G.729 Annex A, iLBC, and Speex codecs are supported. On Android, iOS
and Mac G.711, Speex (wideband) and G729 are supported. Codecs are described with space-delimited
strings. The selected codecs are then used in the SDP body of e.g. SIP INVITE message. This value can
be changed during a call. The following codec strings are supported: “SIREN24”, “SIREN48”, “SPEEX”,
“SPEEX-WB”, “ILBC”, “GSM”, “PCMU”, “PCMA”, and “G729”.
Since codecs are not line-specific, special care must be taken when using multiple lines. The codec set
will be used by all active SIP accounts using this control.
This property is not SIP account specific, and hence, affects all SIP accounts.
When acting as conference host, it is possible to add conference participants thus supporting different
codecs in a single conference. This is useful when adding participants from PSTN gateways which
usually only support a small selection of codecs.

AudioPlaybackDevice
This sets a preferred audio playback device by the index or retrieves the index of the device in use as an
integer. The index is zero-based. This value can be changed during a call.
CallHistoryFileName
This sets or retrieves the file name for storing call histories for outgoing calls and incoming calls as a
string.
CallHistorySize(bOutgoingCall)
This sets or retrieves the size of the call history log for either outgoing calls or incoming calls as an
integer. If bOutgoingCall is true, the call history size for outgoing calls is set or retrieved; otherwise, the
call history size for incoming calls is set or retrieved.
ConferenceLine
This enables or disables a conference of a SelectedLine, or retrieves whether ConferenceLine is in
conference. The default value of this Boolean property is false.
This is not applicable to Android, iOS or Mac OS X environments.
DialupDetected

This retrieves whether or not the computer is connected to the Internet using a modem. This Boolean
property is read-only and is updated each time it is retrieved.
DTMFMode
This sets or retrieves whether the SendDTMF method sends DTMF using the RTP payload (0), SIP INFO
method (1), or inband DTMF (2). The default value is 0.
This property is called on the SelectedSipAccount.
Inband DTMF is designed to work only with high bit rate codecs, such as G711 and G722. For low bit rate
codecs such as G729, RTP payload or SIP INFO should be used instead of inband.
EnableAGC
This sets or retrieves whether or not Auto Gain Control (AGC) is used for the microphone input signal.
This is a Boolean variable and its default value is false. This value can be changed during a call.
EnableDenoise
This sets or retrieves whether or not noise is removed from the microphone input signal. This is a Boolean
value and its default value is true. This value can be changed during a call. This property should be
enabled for better echo cancellation.
EnableEchoCancellation
This sets or retrieves whether or not echo cancellation is enabled. This is a Boolean property and its
default value is true. This value can be changed during a call. For better echo cancellation,
EnableDenoise property must be set to true.

EnableKeepAliveFailover
If this property is true and three consecutive keep-alive responses are not received from the SIP proxy,
the client will try to register to another SIP proxy specified by the SRV domain. If no such SIP proxy is
available, OnConnectionLost event will be fired. If this property is false, the keep-alive mechanism will be
deactivated. The default value of this Boolean property is false.
EnablePreview
This enables or disables preview video or retrieves whether preview video is enabled or disabled. This is
a Boolean property. If its value is false, preview video is disabled.
EnableIceSupport
This sets or retrieves whether or not ICE candidates are used in invite for firewall traversal. ICE stands for
Interactive Connectivity Establishment. This is a Boolean property and its default value is true.
EnableRelaySupport
This sets or retrieves whether or not relayed candidates are used in invite for firewall traversal. Eyeball
Messenger SDK will use a TURN server to obtain these candidates. This is a Boolean property and its
default value is true.

EnableSrtp
This enables or disables Secure RTP one-to-one calls. This property does not support conferencing. This
is a Boolean variable and its default value is false. It can only be set before making a call. The caller has
to enable SRTP, but the callee must support SRTP as well for the call to be secure, although it does not
need to call this property. If the callee does not have SRTP support, an OnSRTPDisabled event will be
fired.
EnableStunSupport
This sets or retrieves whether or not server reflexive candidates are used in invite for firewall traversal.
Eyeball Messenger SDK will use a STUN server to obtain these candidates. This is a Boolean property
and its default value is true.
FrameRate
This sets or retrieves the outgoing frame rate that the control tries to maintain in a video call. This value
cannot exceed 30. If the frame rate is not set explicitly or if the frame rate is set to 0, the frame rate
maybe automatically adjusted by Eyeball Messenger SDK if quality adaptation is enabled.
HashedPassword
When this property is set, the supplied MD5 hashed user name, realm, and password are used for user
authentication (instead of the password being set in the SetAccount() method). When this property is
empty, the user name and password supplied in the SetAccount() method are used for authentication and
the generated hash can be retrieved using this property.

HoldConference
This holds or un-holds a conference or retrieves whether or not a conference is being held. The default
value of this Boolean property is false.
HoldLine
This holds or un-holds SelectedLine, or retrieves whether or not SelectedLine is being held. The default
value of this Boolean property is false. No SIP account needs to be set to call this method.
This property is called on the SIP account associated with SelectedLine.
ImageSize
This sets the image size to be captured, or retrieves the captured image size as an integer. The default
value is 0. This property can be set at any time. OnVideoSizeChange event is fired when the image size
is changed.
The possible values are:
Windows:
0: Small image size (176 x 144, or 192 x 144, if supported by the device)
1: Medium image size (352 x 288, or 320 x 240, if supported by the device)
2: Large image size (640 x 480 if supported by the device)
3: 720p (HD) image size (1280 x 720 if supported by the device)
Android:

0: Small image size (176 x 144)
2: Medium image size (320 x 240)
3: Large image size (352 x 288)
5: VGA image size (640 x 480)
iOS:
5: VGA image size (640 x 480)
Mac OS X:
5: Large image size (640 x 480)
IsLineIdle
This retrieves whether or not the SelectedLine is idle (not in a call) as a Boolean value. This is a read-only
property.
This property is not SIP account specific.
KeepAlivePeriod
The SIP Communicator control can periodically send keep-alive messages to the SIP proxy if keep-alive
mechanism is enabled by the EnableKeepAliveFailover property to verify that the connection to the SIP
proxy is active. If three consecutive keep-alive responses are not received, the OnConnectionLost event
will be fired. The default value for this property is 30 seconds.

LineVolume
This sets or retrieves the volume of a SelectedLine. The value ranges from 1 (silence) to 100 (full
volume). The default value of this property is 100.
MaximumLine
This sets or retrieves the maximum number of lines to be used. This parameter should be set to 1 for
single-line applications. The default value for multiple-line applications is 30. In case all lines are busy,
additional incoming calls will automatically be rejected with a “486 Busy here” response. In those cases,
Eyeball Messenger SDK does not fire notification events.
MuteReceiver
This mutes or un-mutes inbound audio on SelectedLine, or retrieves whether or not inbound audio on
SelectedLine is muted. The default value of this Boolean property is false.
MuteSender
This mutes or un-mutes outbound audio, or retrieves whether or not outbound audio is muted. The default
value of this Boolean property is false.
NoSdpInvite

This defines whether an INVITE message is sent with or without SDP (see RFC 3261). The default value
of this Boolean property is false, i.e. the initial INVITE does carry an SDP body with the initial offer.
This property is called by the SelectedSipAccount.
PauseReceiver
This pauses or un-pauses inbound video on SelectedLine, or retrieves whether or not inbound video on
SelectedLine is paused. The default value of this Boolean property is false.
PauseSender
This pauses or un-pauses outbound video, or retrieves whether or not outbound video is paused. The
default value of this Boolean property is false.
QualityProfile
This sets or retrieves the quality profile used for outbound video as Integer. The possible values are:
0: High frame rate
1: Standard quality
2: High image quality
The default value for this property is 1. At level 0, the captured frame rate is high, but the quality of video
may be low. At level 2, the picture quality is high, but the captured frame rate may be low. Level 1 stands
in-between levels 0 and 1.

RegistrationExpire
The SIP registration expiry period is in seconds in the SIP Expires header of the SIP REGISTER
message. The default value is 1800 seconds. This value will be the preference of the client; however, the
SIP server’s choices of the expiry period have preference.
RegistrationPeriod
This is the period after which a SIP registration is refreshed. The default value is RegistrationExpire-10
seconds (1790). Similar to RegistrationExpire, the SIP server’s choice of expiry period will override this
setting. If not set or overridden by the SIP server, this value is set to RegistrationExpire-10 seconds.
Example: The SDK selects registration expiry of 1800 seconds and RegistrationPeriod of 1790 seconds.
The SIP server reduces this to 300 seconds. Eyeball Messenger SDK will re-register after 290 seconds.
SelectedLine
This sets a line to be selected or retrieves a line that is currently being selected as an integer. Some
properties and methods, such as HoldLine, Call, and GetDisplayName perform operations on the line
specified by SelectedLine.
SelectedSipAccount
This sets or retrieves the selected SIP account. If the SIP account does not exist, it will be created and
selected. The SIP account can be selected with a numerical non-negative integer value between 0 and
MAXIMUM_SIP_ACCOUNT – 1, inclusive. The value of MAXIMUM_SIP_ACCOUNT is 10 by default. SIP
account 0 is the default account, and is created automatically when the application is launched.
TransportMode

This sets or retrieves the transport mode as a string. The transport mode can be “UDP”, “TCP”, or “TLS”.
The transport mode is used for DNS SRV lookups, e.g. _sip._udp.yourdomain.com. In case Eyeball
Messenger SDK is located behind an HTTP proxy, it uses proxy tunneling (HTTPS CONNECT) to contact
the server. In this case, the HTTP proxy host, port, username, and password (also domain for NTLM
proxy authentication) must be defined. Note that all transport modes are possible when behind a proxy;
the UDP transport mode is possible by using the STUN/TURN server. The transport mode string is case-
insensitive.
UserMode
This sets or retrieves the user mode as a string. The user mode can be “available”, “away”, or “dnd”.
Eyeball Messenger SDK will auto respond to an incoming call with “SIP 480 Temporarily Unavailable" and
"SIP 486 Busy Here” based on user mode “away” and “dnd” respectively. Eyeball Messenger SDK will get
the incoming call with “available” user mode.
VideoCaptureDevice
This sets or retrieves the zero-based index of selected video capture device as an Integer. This value can
be changed while in a call.
VideoCaptureInput
This sets or retrieves the zero-based index of selected video capture input as an integer. This value can
be changed while in a call.

VideoCodecs
This sets or retrieves preferred video codecs. Currently, EyeStream, H.263, and H264 codecs are
supported. On Android, iOS and Mac OS X only H264 is supported. Codecs are described with space-
delimited strings. These codecs are specified in the SDP body of the SIP INVITE message. This value
can be changed while in a call. The default value is “EyeStream H263”. Since codecs are not line-
specific, special care must be taken when using multiple lines. The possible parameters are: “Eyestream”,
“H263”, “H263-1998” (H263+), and “H264”. When attempting an audio/video call to a client that does not
support the codecs selected in Eyeball Messenger SDK, the call will be completed as an audio only call.
In a conference, only one codec is supported. It is not possible to add participants that do not support the
video codec used by the existing conference participants.

6.2. Messenger SDK Methods
Methods
AttachVideoWindow(nLine, nWnd)
This attaches a given video window to the display video received from the specified line. A separate
instance of VideoWindowCtl is needed to display each video window.
nLine:
This is the line indicating a call for video source. If nLine is -1, window is used to display the preview
video for the current user.
nWnd:
This is the window handle of the video window. This is returned by the GetVideoWindow method of
VideoWindowCtl.
iOS:
AttachVideoWindow(int iLine, void *pWnd)
pWnd:
Reference to an UIView for camera preview surface, and to an UIImageView for remote video surface.
Mac:
AttachVideoWindow(int iLine, void *pWnd)
pWnd:
Reference to an NSView for camera preview surface, and to an NSImageView for remote video surface.

This method is called on the SIP account associated with nLine.
This is not applicable to Android environments.
AttachVideoWindowEx(nLine, nIndex, nWnd)
This attaches a given video window to the display video received from the specified line. A separate
instance of VideoWindowCtl is needed to display each video window.
nLine:
This is the line indicating a call for video source. If nLine is -1, window is used to display the preview
video for the current user.
nIndex:
This is the user index in the conference. It is 0 if not in a conference.
nWnd:
This is the window handle of the video window. This is returned by the GetVideoWindow method of
VideoWindowCtl.
Call(sTargetURI, sDomain, bAnonymous, bPhone,
bConf)
This makes a SIP call to a party specified by URI sTargetURI. If the line specified by SelectedLine is
reserved with GrabLine, that line is used to make the call; otherwise, Call will implicitly reserve a line,
modify SelectedLine to be that line, and use that line to make the call. It is possible to add the new call to
an existing conference or start a new conference with it using the parameter bConf. When an anonymous
call is used, the From and Contact headers in the SIP INVITE are replaced in accordance with RFC
3323. When the callee is a phone device ( bPhone set to true), “user=phone” is placed in request URI
(sip: +16049215993@gateway.eyeball.com;user=phone).
sTargetURI:
SIP URI to call
sDomain:

Domain of the SIP server
bAnonymous:
Indicates whether to make anonymous call
bPhone:
Indicates whether the call is a phone call
bConf:
Indicates whether the new call will be added to an existing conference or creates a new conference
This method is called on the SelectedSipAccount.
ConferenceMemberList(bVideoOnly)
This returns a list of participants in a conference.
bVideoOnly:
If this parameter is true, returns a list of participants in a video and audio conference; otherwise, returns a
list of ALL participants (i.e., including those with audio-only).
This method is not SIPaccount specific.
EnableRegistration(nIndex, bEnable)
This enables or disables a proxy server registration when the method Register is called. When a proxy
server is disabled, calling Register will not register that particular proxy server. This method is used for
the purpose of registering at multiple proxy servers. This method is called on the SelectedSipAccount.
nIndex:
Index of proxy server to be enabled or disabled on registration
bEnable:

If this is true, the proxy server specified by nIndex will be registered when Register is called; otherwise, it
will not be registered.
EndCall(bEndAllCalls)
This ends a call (specified by SelectedLine) or ends all calls associated with the currently selected
account.
bEndAllCalls:
If this is true, calls on all lines associated with the SIP account on the SelectedSipAccount will be ended;
otherwise, only the call on SelectedLine is ended.
If bEndAllCalls is false, this method is called on the SIP account associated with the SelectedLine, and
ends the call on the SelectedLine only. If bEndAllCalls is true, this method is called on the
SelectedSipAccount, but ends calls on all lines associated with the SelectedSipAccount.
EndData(sTargetURI)
This ends a data transfer to/from a party specified by URI sTargetURI.
sTargetURI:
SIP URI to end data transfer
ForwardCall(nLine, sForwardURI, sReason)
This forwards an incoming call at a specific line to a URI. This method may be invoked to respond to the
OnCallRequest event. The SIP Contact header of the response includes the Diversion header to indicate
why and from where the request was diverted.
nLine:
The line indicating the incoming call to be forwarded. The line of an incoming call can be retrieved from
the first element of array returned by OnCallRequest event.
sForwardURI:
URI of where the user forwards the call to

sReason:
Reason for forwarding incoming call
GetAudioCaptureDeviceName()
This returns audio capture device name as a VB array. Each entry contains a single element, namely,
the text description of the audio capture device.
This method is not SIP account specific.
GetAudioReceiverStat()
This returns audio receiver statistics of the currently selected line as a VB array of eight elements on
Windows, array of string on Android, and vector of string on iOS.
Element 1 (Codec, String):
Audio codec
Element 2 (Bit rate, Float):
Audio receiving bit rate
Element 3 (Buffer size, Integer):
Audio receive buffer size in ms
Element 4 (Audio resynchronization count, Integer):
Number of times the audio receive buffer is reset and re-synchronized
Element 5 (Packets received, Integer):
Number of packets received
Element 6 (Packets lost, Integer):

Number of packets lost
Element 7 (Packets late, Integer):
Number of late packets
Element 8 (Loss rate, Float):
Packet loss rate
GetAudioSenderStat()
This returns audio sender statistics of the currently selected line as a VB array of three elements on
windows, array of string on Android and vector of string on iOS.
Audio codec
Audio receiving bit rate
Element 3 (Packets sent, Integer):
Number of packets sent
GetCallHistory(bOutgoing)
This returns the outgoing call history or incoming call history as a VB array on Windows, array of string on
Android, and vector of string on iOS, an array of elements for all call history entries.
Each entry contains 4 elements ordered as follows:
Element 1 (Display name, String):
Display name of remote user in the call

Element 2 (URI, String):
URI of the remote user in the call
Element 3 (Calling time, String):
Time and date of when the call is made
Element 4 (Duration, Integer):
Duration of the call in seconds
In the array, each entry is followed by another entry, and thus the array contains a total number of
elements equal to four times the number of call history entries. For example, if one wants to get the
calling time of the third call history entry, one should get the eleventh element from the array.
bOutgoing:
If this is true, the outgoing call history is returned; otherwise, the incoming call history is returned.
GetCallURI()
This returns the URI of the remote user in the current call (specified by current value of SelectedLine).
GetDisplayName()
This returns the display name of the remote user in the current call (specified by current value of
SelectedLine).
GetFirewallStatus(nLine)
This returns the status of the firewall traversal on the call line specified by nLine.
Possible values:

“Unknown”:
Firewall traversal status is unknown
“Peer-to-peer”:
Firewall traversal succeeded and call completed peer-to-peer
“UDP Relay”:
Firewall traversal succeeded and call completed using UDP relay
“TCP Relay”:
Firewall traversal succeeded and call completed using TCP relay
“HTTP Relay”:
Firewall traversal succeeded and call completed using HTTP relay
“Fail”:
Firewall traversal failed
nLIne:
The line indicating a call
GetHttpProxyAddr()
This function returns the HTTP proxy address.
GetHttpProxyDomain()

This returns the case-sensitive HTTP proxy domain. This value is valid only when NTLM authentication is
used.
GetHttpProxyPassword()
This returns the case-sensitive HTTP proxy password.
GetHttpProxyPort()
This retrieves the HTTP proxy port.
GetHttpProxyUserName()
This returns the case-sensitive HTTP proxy user name.
GetLineStatus()
This returns the status of the current call (specified by the current value of SelectedLine).
Possible values:
“idle”:
No connection is made
“calling”:

Currently making a call
“ringing”:
The call is ringing
“proceeding”:
The call is proceeding
“established”:
The call is established successfully
“on hold”:
The call is currently on hold
“on hold by remote”:
The call is currently on hold by remote party
“on hold by both”:
The call is currently on hold by both parties
GetVideoCaptureDeviceName()
This returns the video capture device name as a VB array. Each entry contains a single element, namely,
the text description of the device.
GetVideoCaptureInputName()
This returns the video capture input name as a VB array. Each entry contains a single element, namely,
the text description of the video input.

GetVideoReceiverStat()
This returns video receiver statistics of the currently selected line (see SipCommCtl.SelectedLine) as a
VB array of eight elements.
Video codec
Video receiving bit rate
Element 3 (Frame rate, Float):
Video receiver frame rate
Element 4 ((Frames received, Integer):
Number of frames received
Element 5 (Frames dropped, Integer):
Number of frames dropped
Element 6 (Packets received, Integer):
Number of packets received
Element 7 (Packets lost, Integer):
Number of packets lost
Element 8 (Loss rate, Float):
Packet loss rate

GetVideoSenderStat()
This returns the video sender statistics of the currently selected line (see SipCommCtl.SelectedLine) as a
VB array of eight elements.
Video codec
Video sending bit rate
Element 3 (Frame rate, Float):
Video sending frame rate
Element 4 ((Frames sent, Integer):
Number of frames sent
Element 5 (Frames dropped, Integer):
Number of frames dropped
Element 6 (Packets sent, Integer):
Number of packets sent
Element 7 (Frames lost, Float):
Number of packets not received by remote user
Element 8 (Packets rate, Float):
Packet loss rate
GetVideoWindowCount(nLine)
This returns the number of video windows associated with the conference on the given line.

GrabLine(nLineToGrab)
This reserves a line to make a SIP call. When a line is reserved, it will not be used for receiving an
incoming call. There can only be one line being reserved at a time. A reserved line is released once
ReleaseLine is called or once Call is called on the line. If there is an error reserving the line, -1 is
returned; otherwise, the line being reserved is returned as an integer.
nLineToGrab:
Specifies a line to be reserved. If this is –1, the control will choose a line that is not in use and return that
line as Integer.
HasCamera()
This returns whether or not there is any camera available for capturing video data.
HasMicrophone()
This returns whether or not there is any microphone available for capturing audio data.
IsAudioCall()
This returns true if the call on the SelectedLine has audio.

IsIncomingCall()
This returns true if the call on the SelectedLine is incoming.
IsRegistered()
This returns true if at least one proxy has been registered.
IsVideoCall()
This returns true if the call on the SelectedLine has video.
LoadCallHistory()
This loads the call history, both outgoing call history and incoming call history, from the file specified by
the CallHistoryFileName property.
Logout()
This logs out from all proxy server(s) the user has registered with.

MWISubscribe(sTargetURI)
This calls the SIP SUBSCRIBE method to request current state and state updates from a remote URI.
sTargetURI:
The remote URI to subscribe to
MWIUnSubscribe()
This un-subscribes from a previous subscription on a remote URI.
sTargetURI:
The remote URI to un-subscribe from
RecvData(sTargetURI)
This receives data from a party specified by URI sTargetURI. This method should be invoked to respond
to the OnDataUpdate event. sTargetURI must be in the format: user@domain, which is returned in the
first element of the array returned by OnDataUpdate.
sTargetURI:
SIP URI to receive data
sData:
Data to be received
This method is called on the SIP account associated with sTargetURI.

This is not applicable to Android, iOS or Mac OS X environments
Register()
This registers proxy server(s) specified with the method SetProxy using the User ID, password, and
display name set with methods SetAccount and SetDisplayName, respectively. Register is required
before accessing many of the other methods.
ReleaseLine()
This un-reserves the line being reserved through the method GrabLine. This method only needs to be
called if one wants to un-reserve a reserved line that has not been used to make a call. If Call is used
while the reserved line is SelectedLine, the line is automatically un-reserved.
RemoveCallHistory(bOutgoing, nIndex)
This removes a call history entry from either outgoing call history or incoming call history for all SIP
accounts.
bOutgoing:
If this is true, a specified call entry from outgoing call history is removed; otherwise, a call entry from the
incoming call history is removed.
nIndex:
A zero-based index specifying an entry to be removed from a call history
RemoveSipAccount(nAccnt)

This removes the SIP account with ID nAccnt. This method logs out of the account first, releases any
resources held by it, then removes it. The value of SelectedSipAccount becomes -1 after this function
succeeds.
nAccnt:
ID of the SIP account to remove
ResetAudioReceiverStat()
This resets the audio receiver statistics.
ResetAudioSenderStat()
This resets the audio sender statistics.
ResetVideoReceiverStat()
This resets the video receiver statistics.
ResetVideoSenderStat()
This resets the video sender statistics.

RespondCall(nLine, bAccept, bconf)
This accepts or rejects the incoming call at a specific line. This method should be invoked to respond to
the OnCallRequest event.
nLine:
This is the line indicating the incoming call to be accepted or rejected. The line of an incoming call can be
retrieved from the first element of array returned by OnCallRequest event.
bAccept:
True to accept call or false to reject call
bConf:
True to accept call in Conference, otherwise false
RespondData(sTargetURI, bAccept)
This accepts or rejects data transfer requests. This method should be invoked to respond to the
OnDataRequest event. sTargetURI must be in the format: user@domain, which is returned in the first
element of the array returned by OnDataUpdate.
sTargetURI:
SIP URI to receive data from
bAccept:
True to accept data or false to reject data
This method is called on the SIP account associated with sTargetURI.
RespondReinvite(nLine)

This must be called after the OnReinviteRequest event is fired. Audio/video codecs may be changed and
audio/video can be enabled or disabled.
nLine:
The line on which the re-invite response should be sent. nLine can be retrieved from the array returned by
OnReinviteRequest.
SaveCallHistory()
This saves current call histories, both outgoing call history and incoming call history, into a file specified
by the CallHistoryFileName property.
SendData(sTargetURI, sData)
This sends a data transfer request (SIP INVITE) to a party specified by URI sTargetURI. If no domain is
specified in sTargetURI, the domain of the currently selected SIP account will be used.
sTargetURI:
SIP URI to send data
sData:
Data to be sent
SendDTMF(sKey)

This sends the DTMF message corresponding to a specified key to the current call (specified by current
value of SelectedLine). If no call is established at SelectedLine, nothing is sent.
The DTMF mode can be selected using the property DTMFMode.
sKey:
A valid key specifying a DTMF to be sent
SendTextMessage(sTargetURI, sTextMsg)
This sends a text message to a party specified by sTargetURI. SIP MESSAGE is used to transmit the
data to the remote party.
sTargetURI:
SIP URI to send the text message to
sTextMsg:
Text message to be sent
SetAccount(nIndex, sUserId, sAuthenticationId,
sPassword)
This sets the user ID and password to be used to register at a proxy server.
nIndex:
This is the index of the proxy server this accounts to be used to register at. It is used for the purpose of
registering at multiple proxy servers.
sUserId:
This is the user ID used to register at the proxy server.
sAuthenticationId:
This is the user ID used for user authentication. This can be different from sUserId.

sPassword:
This is the password used to register at the proxy server.
SetDisplayName(nIndex, sDisplayName)
This sets the display name to be used to register at a proxy server.
nIndex:
This is the index of the proxy server this display name is to be used to register at. This is used for the
purpose of registering at multiple proxy servers.
sDisplayName:
This is the display name used to register at the proxy server.
SetDomain(nIndex, sDomain)
nIndex:
Index of the proxy server to be associated with this domain
sDomain:
Domain to be used for registration at the proxy server
SetHttpProxyAuthentication(sUserName, sPassword,
sDomain)
This function sets the username, password, and domain for HTTP proxy authentication. The domain
parameter is only required for NTLM authentication. In case of authentication failure, the
OnRegisterResponse event is fired with the reason for the failure.

This function should be called before the HTTP proxy is set in SetNATTraversalServer.
SetNATTraversalServer(nServerType, bstrAddr, nPort,
bDone)
This function initializes the underlying AnyFirewall Engine by setting the necessary servers for performing
firewall traversal.
nServerType:
An enum indicating the type of server to be set
bstrAddr:
IP address of the server
nPort:
Port of the server
bDone:
This is false if more servers remain to be set, and True if this is the final server to be set. Firewall
detection will start after all servers have been set.
Server Type Description

eServerSRV
The DNS SRV domain name that is used to locate the SIP, STUN, TURN and
STUN-Relay/TURN servers. The port parameter for the server type is ignored.
The following DNS SRV queries will be made:
_sip._tcp.<srvdomain> SIP proxy when TCP is used
_sip._udp.<srvdomain> SIP proxy when UDP is used
_sips._tcp.<srvdomain> SIP proxy when TLS is used
_stun._udp.<srvdomain>STUN server (UDP)
_stun._tcp.<srvdomain>STUN server (TCP)
_turn._udp.<srvdomain>STUN-Relay/TURN server (UDP)
_turn._tc alive p.<srvdomain>STUN-Relay/TURN server (TCP)
eServerHttpProxy The HTTP Proxy server, for users using a proxy server
eServerStunUdp* The UDP STUN server
eServerStunTcp* The TCP STUN server
eServerTurnUdp* The UDP STUN-Relay/TURN server
eServerTurnTcp* The TCP STUN-Relay/TURN server
*These parameters will be used if eServerSRV is not set or the DNS SRV lookup fails.
This method is called on the SelectedSipAccount. However, STUN servers are independent to the SIP
accounts, and thus the STUN servers associated with the most recent call with eServerSRV will be used.
SetProxyServer(nIndex, sServerAddr, nPort)
This sets the address and port of a SIP proxy to register at. This value will be used if the DNS SRV query
for the SIP proxy (see SetNATTraversalServer) fails or the DNS SRV domain is not set.
nIndex:
This is the index of the SIP proxy used for purpose of registering at multiple proxy servers. Index is zero
based. If multiple-proxy registration is not supported, the index should always be set to zero.
sServerAddr:
Address of the SIP proxy
nPort:
Port of the SIP proxy

SetSipEventHandler(sipEventHandler)
This sets the event handler for handing events from the SipComm control. This must implement the
SipEventHandler interface. The SipEventHandler is an object which implements SipEventHandler.
Please check the sample application code.
This is applicable to the Android environment only.
SetTURNUsernamePassword (sUsername,
sPassword)
This sets the authentication information for the TURN server.
sUsername:
Username of the TURN server
sPassword:
Password of the TURN server
This function should be called before bDone is set to true in SetNATTraversalServer.
SetVideoSource()
This displays a device-specific dialog box where the user can control the video source. The video source
dialog box may contain controls that select input sources, alter hue, contrast, brightness of image, and
modify the video quality before digitizing images into the frame buffer. These controls affect all SIP
accounts.

SipCommInit
This initializes the SipComm control.
This is applicable to the Android environment only.
TakeIncomingVideoSnapshot(sFileName, nIndex)
This takes a snapshot of the remote video and saves it to a file. The image is compressed using
JPEG. JPEG control must be installed.
sFileName:
File to save snapshot
nIndex:
User index in the conference; 0 if not in a conference
TakeSnapshot(sFileName)
This takes a snapshot of the preview video and saves it to a file. The image is compressed using
JPEG. JPEG control must be installed.
sFileName:
File to save snapshot

TransferCall(sURI)
This performs an unattended call transfer of the selected line. The user must be in a call, which was
initiated by other party. Only the callee can perform a call transfer.
sURI:
URI to transfer call to

6.3. Messenger SDK Notification Events
Notification Events
The following notification events are supported by the SIP Communicator.
Event Dispatch ID Event Name
1 OnRegisterResponse
2 OnCallResponse
3 OnCallRequest
4 OnEndCall
5 OnSipMessage
6 OnReinviteRequest
7 OnReinviteResponse
8 OnVideoSizeChanged
9 OnConnectionLost
10 OnLogoutComplete
11 OnMessageWaitingIndication
14 OnConferenceMemberListUpdate
16 OnSubscribeResponse
17 OnFirewallStatusChange
18 OnMoveToConference
19 OnTextMessage
20 OnDataRequest
21 OnDataUpdate
22 OnBandwidthWarning
23 OnSRTPDisabled

Events may return the following status codes or response codes. Status codes correspond to SIP
message status codes. Below is a table of possible status codes:
100:
Trying
180:
Ringing
183:
Session Progress
200:
OK
Below is a table of possible response values:
0:
Progress
1:
Success
2:
Failure
3:
Timeout
Events may contain an integer ID of the SIP account they belong to. The account ID is always an ID of a
local account on the local machine.

OnRegisterResponse(aResponseInfo)
This fires when registration status is changed.
aResponseInfo is a VB-array containing the following elements:
Element 1 (Response value, Integer):
This is the value representing the registration status.
Element 2 (Status code, Integer):
This is a status code. This is either the status code of the response returned by the SIP proxy (e.g., 200)
or it is 0. It is also 0 in case of HTTP proxy errors (see error strings below).
Element 3 (Reason, String):
This is a reason string that is either the response returned by the SIP proxy (e.g., “Ok”) or an error
description, e.g. an error message related to HTTP proxy tunneling.
Element 4 (SIP proxy index, Integer):
This is the index of the SIP proxy that sent this response.
Element 5 (SIP account ID, Integer):
This is the ID of the SIP account receiving the register response.
One of the following response values (element 1) will be returned:
0:
Progress
1:
Success
2:
Failure

3:
Timeout
In case of an error message received from the SIP proxy, the status code of the error message is given in
element 2 of the VB array. For example, an incorrect username or password will be signaled as 401. For
other errors like incorrect IP address of SIP or HTTP proxy, one the following reason strings will be
returned:
"HTTP Proxy authentication failure."
The control failed to authenticate to the HTTP proxy with the given username and password.
"Tcp connection error."
This message is returned when the TCP connection to the SIP proxy could not be established. Possible
reasons include incorrect IP address or port of SIP proxy or HTTP proxy, TCP connection loss or SIP
proxy not supporting TCP connections. This can only happen in case TCP or TLS were selected as
TransportMode.
"Registration timed out."
This error is returned when the SIP registration timed out.
OnCallResponse(aResponseInfo)
This fires when a call response is received.
Element 1 (Incoming line, Integer):
Line indicating call for which response is received
Element 2 (Response value, Integer):
Code representing call response status
Status code returned by proxy server

Reason string returned by proxy server
Element 5 (Display name, Integer):
Display name of remote user sending this response
URI of remote user sending this response
Element 7 (Video call flag, Boolean):
True if it is a video/audio call or false if it is an audio only call
Element 8: (SIP account ID, Integer):
ID of the SIP account receiving the call response
Element 9: (Early media flag, Boolean):
True for 180/183 call response with early media; false otherwise
Element 10: (Whether peer supports ICE or not, Integer):
0: peer does not support ICE
1: Peer supports ICE
-1: Unknown
Below is a table of possible response values:
0:
Progress
1:
Success
2:
Failure

3:
Timeout
OnCallRequest(aRequestInfo)
This fires when a call request is received. RespondCall or ForwardCall must be invoked to respond to
this event.
aRequestInfo is a VB-array containing the following elements:
Line assigned to incoming call
Display name of remote user sending this request
URI of remote user sending this request
Element 5 (SPIT rating, Integer):
SPIT rating from AntiSPITTM server, or -1 for no rating
Element 6(SIP account ID, Integer):
ID of the SIP account receiving the call request
Element 7 (SRTP, String):
“SRTP” if a secure call is requested; otherwise, “”.

OnEndCall(aCallInfo)
This fires when a call is ended by the remote user.
aCallInfo is a VB-array containing the following elements:
Line associated with the call that ended
Display name of remote user in the ended call
URI of remote user who ended the call
ID of the SIP account whose call was ended by remote user
OnSipMessage(aMessageInfo)
This fires when there is an outbound or inbound SIP message.
aMessageInfo is a VB-array containing the following elements:
Element 1 (Outgoing, Integer):
If this number is 1, then the message is an outbound message; otherwise, it is an inbound message.
Element 2 (Proxy name, String):
Address of proxy server
Element 3 (Message, String):
SIP message content

ID of the SIP account to which the SIP message belongs
OnReinviteRequest(aRequestInfo)
This fires when a call re-invite request is received. RespondReinvite must be invoked to respond to this
event.
aRequestInfo is a VB-array containing the following elements:
Element 4 (Add audio, Integer):
Add audio to this call
Element 5 (Add video, Integer):
Add video to this call
ID of the SIP account receiving the re-invite request
OnReinviteResponse(aResponseInfo)
This fires when a call re-invite response is received.

Element 4 (Add audio, Integer):
Set to 1 when other party accepts adding audio to call
Element 5 (Add video, Integer):
Set to 1 when other party accepts adding video to call
ID of the SIP account receiving the re-invite request
OnVideoSizeChange(aSizeChangeInfo)
This is fired when ImageSize property is set to change the image size to be captured and when capture
video size is changed on the remote end.
aSizeChangeInfo is a VB-array containing the following elements:
Element 1 (Window handle, Integer):
Window handle of the video container that has size changed (N/A on iOS)
Element 2 (Width, Integer):
Width of the video after size change

Element 3 (Height, Integer):
Height of the video after size change
Android:
OnVideoSizeChange(int iWidth, int iHeight)
OnConnectionLost(aConnectionLostInfo)
This fires when the connection to the SIP proxy is lost. This event will only be fired when
EnableKeepAliveFailover property is set to true and all configured SIP proxies (DNS SRV and/or backup
FQDN) fail to respond to three consecutive keep-alive messages.
aConnectionLostInfo is a VB-array containing the following element:
ID of the SIP account whose connection was lost
OnLogoutComplete(aLogoutCompleteInfo)
This fires when the logout process is completed.
Please note that the logout process can take a significant amount of time. When the proxy cannot be
reached, the un-registration process fails over to other available SIP proxies. The un-registration process
completes when the 200 OK response is received from a proxy. When there are no proxies available for
un-registration (i.e., all proxies have failed), this event is not fired.
aLogoutCompleteInfo is a VB-array containing the following element:
ID of the SIP account that was logged out of

OnMessageWaitingIndication(aDataInfo)
This fires when a message waiting indication event is received.
aDataInfo is a VB-array containing the following elements:
Element 1 (Waiting, Boolean):
If this variable is true, the status of the message we subscribed to is waiting.
A SIP URI identifying the subscriber account to which this message corresponds
Element 3 (Class, String):
Context class of the message as one of the following values:
“Voice-Message”: The message type is voice message.
“Fax-Message”: The message type is fax message.
“Pager-Message”: the message type is pager message.
“Multimedia-Message”: The message type is multimedia message.
“Text-Message”: The message type is text message.
“none”: The message type is none of the above.
Element 4 (Type, String):
A string in the format new/old where
new: an integer denoting the number of new messages
old: an integer denoting the number of old messages
Element 5 (Urgency, String):
A string in the format UrgentNew/UrgentOld, where
UrgentNew: an integer denoting the number of new urgent messages.

UrgentOld: an integer denoting the number of old urgent messages.
OnConferenceMemberListUpdate(aListInfo)
This fires when the conference host adds or removes a client to the conference.
Only participants will get this event. Once the event is fired, participants can retrieve the list of conference
members by calling ConferenceMemberList().
aListInfo is a VB-array containing the following elements:
Line associated with a call or a conference
ID of the SIP account associated with the call or conference
OnSubscribeResponse(aListInfo)
This fires when subscribe/un-subscribe are successfully accepted.
aListInfo is a VB-array containing the following elements:
This is the status code of the response returned by the SIP proxy (e.g., 202).
This is a reason string that is either the response returned by the SIP proxy (e.g., “Accepted”) or an error
description.

Element 3 (Event Type, Integer):
MWI or conference event
ID of the SIP account receiving the register response
Element 5 (State, Integer):
State is 1 when the subscribe request is accepted by the server, and State is 0 when the un-subscribe
request is accepted by the server.
OnFirewallStatusChange(aFirewallInfo)
This fires when the firewall status changes.
aFirewallInfo is a VB-array containing following elements:
Element 1 (Line, Integer):
Line associated with the call
Element 2 (Display Name, String):
Displays the name of the remote user in the call
Element 3 (Target URI, String):
URI of the remote user in the call
Element 5 (Status, String):
1. Firewall status is shown as one of the following strings:
"Firewall type: Unknown", "Firewall type: None", "Firewall type: NAT", "Firewall type: TCP only", "Firewall
type: Proxy" or "Firewall type: Blocked" when SDK detects the firewall type. The Line will be -1 at that
time.
2. The following strings will show the status of a call:

Eyeball Messenger SDK V10.0 Developer Reference Guide

Eyeball Messenger SDK V10.0 Developer Reference Guide

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Was ist angesagt?

Was ist angesagt? (20)

Ähnlich wie Eyeball Messenger SDK V10.0 Developer Reference Guide

Ähnlich wie Eyeball Messenger SDK V10.0 Developer Reference Guide (20)

Mehr von Eyeball Networks

Mehr von Eyeball Networks (7)

Kürzlich hochgeladen

Kürzlich hochgeladen (20)

Eyeball Messenger SDK V10.0 Developer Reference Guide