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

https://eyeballnetworks.atlassian.net/browse/XEP-0085




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);


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("[email protected]", 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: [email protected];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)

mailto:user@domain


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.



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):




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:


“Trying”: Trying to traverse the firewall.

“Success”: Firewall traversal succeeded

“Fail”: Firewall traversal failed

“ICE check successfully completed”: Firewall traversal succeeded using ICE.

“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.

“Relay error”: Firewall traversal failed to use relay.


ID of the SIP account for which Firewall status changed

OnMoveToConference(aMoveToConferenceInfo)

This fires when the call is converted to a conference by the remote host. The value nLine given specifies the call that is converted.

aMoveToConferenceInfo is a VB-array containing the following elements:

Element 1 (Line, Integer):

The ID of the line being moved to a conference

Element 2 (SIP account, Integer):

The ID of the SIP account associated with the line from Element 1

Element 3 (Joined/Removed from a conference, Boolean):

This parameter is true if the participant was successfully moved into (i.e., joined) a conference. It is false if the participant was successfully removed from a conference.

OnTextMessage(aInfo)


Fires when a text message is received contained in a SIP MESSAGE.

aInfo is a VB-array containing following elements:


Display name of the sender

Element 2 (Target URI, String):

URI of the sender

Element 3 (Text Message, String):

Text message received


ID of the SIP account receiving the text message

OnDataRequest(aDataInfo)

Fires when a data transfer request is received.

RespondData must be invoked to respond to this event.

aRequestInfo is a VB-array containing following elements:




ID of the SIP account receiving the data transfer request



OnDataUpdate(aDataInfo)

This fires when data is received or an error occurred during data transfer.

aDataInfo is a VB-array containing following elements:


URI of remote user sending this request. The returned URI is in the form userid@domain

Element 2 (Data update type, String):

Defines the type of update:

“Recv Status” – data was received

“Send Status” – data was sent

Element 3 (Data Progress, String):

Data transfer progress will be indicated by a value between “0” and “100”. After the completed data transfer, it is set to “Data”. When the data transfer is closed by the remote user, this is set to “Close.”


ID of the SIP account receiving the update.


OnBandwidthWarning(aDataInfo)

This fires if the outgoing bit rate exceeds 128 kbps after making or accepting a call.

aDataInfo is a VB-array containing following elements:

Element 1 (Line number, integer):

Line number of that call



Display name of the remote user in the call





Element 5 (Warning message, String):

Warning message


ID of the SIP account used in the call


OnSRTPDisabled(aSrtpInfo)

This fires if the caller made an SRTP call, but the callee has no SRTP support. The call will be established, but the user will be notified by this event that the call is unsecure.

Element 1 (Incoming line, integer):

Line indicating call for which the call is non-secure

Element 2 (SIP Account ID, Integer):

ID of the SIP account this call belongs to


URI of remote user who accepted this non-secure call


6.4. Messenger SDK Error Handling

Error Handling

Windows: SipCommCtl returns the error code 0x80004005 (in hexadecimal format) as well as error descriptions for all errors. These errors are thrown as exceptions in JScript. The following sample code shows how to handle these errors in JScript:

try

{

SipCommCtl.Call(sRemoteURI);

}

catch(e)

{

alert(“Error description:” + e.description);

}

Android:

SipCommOnError(String sError) event is fired.

iOS, Mac OS X:

OnError(const string &sError) event is fired.


7. Messenger SDK: XMPP Communicator

XMPP Communicator

For the list of features supported by the XMPP Communicator control, please see the complete features table in the Introduction section of this document.

Read more in the following sections:

7.1. Messenger SDK: Properties

7.2. Messenger SDK: Methods

7.3. Messenger SDK: Notification Events

7.4. Messenger SDK: Error Handling


7.1. Messenger SDK: Properties

Properties

AllowViewMyState(sUserId)

This sets or retrieves whether or not to allow the remote user to see my state.

sUserId:

Remote user ID

Implementation of this feature is server dependent.

BlockContactMessage(sUserId)

This sets or retrieves whether or not to block an incoming message from remote user.

sUserId:

Remote user ID


ContactDisplayName(sUserId)

This is the contact display name. The display name is a local property, i.e., it is reflected only on the current user’s contact list. The display name is stored at XMPP server.


sUserId:

User ID of contact

Domain

This is the XMPP domain. This is used when opening a connection to the XMPP server.

HashedPassword

When this property is set, the supplied MD5 hashed user name and password is used for user authentication (instead of the password set in Login() method). When this property is empty, the user name and password supplied in the Login() method is used for authentication and generated hash is placed in this property.

IgnoreResource

Set this property to true if you do not want to use resource. Resource is an arbitrary string enabling multiple logins of the same user.

IsSubscriptionPending(sUserId)

This property is true when the user subscription is in a pending state, i.e., not authorized by another remote party.

sUserId:

Remote user ID

This is a read only property.

KeepAlivePeriod


The client periodically sends keep-alive messages to the server. The default value is 30 seconds. Setting this to 0 disables the keep-alive mechanism.

Nickname

This sets the nickname for the current user. This nickname is stored in the XMPP server’s private XML storage. It is used when sending an add contact request to a remote user triggered by AddContact() method. It is also sent to contacts in the contact list upon login. When a message is sent in a new chat session, the nickname will also be sent to the recipient.

SeeContactState(sUserId)

This sets or retrieves whether or not to see a remote user’s state.

sUserId:

Remote user ID


Version

This is the client version number as a string. The XMPP server may check the client version number and determine whether a client update is necessary.



Methods

AcceptFileTransfer(nFileId, sFileName, bAccept)

This method should be called to reply to a file transfer request when OnFileTransferRequest() event is fired. A standard save file dialog will pop up for choosing a file if the file name specified is empty.

nFileId:

This is the file ID of the file transfer to be accepted/declined. The file ID is available from the OnFileTransferRequest() event.

sFileName:

Local file name used to save the file

bAccept:

Specify true for accept and false to decline the file transfer


AddBlock(sUserId)

This adds the given user ID to the block list. sUserId is also removed from contact list if applicable.

sUserId:

User ID of given user to block


AddContact(sUserId, sFirstName, sLastName, sDisplayName, sGroupName)

This adds the specified user to the current user’s contact list. Add contact request is sent to XMPP server for user authorization.

sUserId:

Remote user ID to be added

sFirstName:

First name of user to be added

sLastName:

Last name of user to be added

sDisplayName:

Local display name of remote user to be added

sGroupName:

Group of user to be added

AddContactGroup(sUserId, sGroup)

This adds a contact to a specific group. If the group does not exist, it will be created.

sUserID:

User ID to be added to a group

sGroup:

Group that the contact will be added to


AddContactResponse(sUserId, bAccept)

This responds to an add-contact request. This method should be called in response to the OnAddContactRequest event.

sUserID:

User ID of request-sender

bAccept:

True to accept request, false to reject

CancelFileTransfer(nFileId)

This cancels an ongoing file transfer. The file transfer can be cancelled by either sender or receiver.

nFileId:

File ID of the file transfer to be cancelled


ChangeGroupName(sUserId, sOldGroup, sNewGroup)

This changes the group of a user. The user will be removed from the old group and added to the new group.

sUserId:

User ID for which group will be changed

sOldGroup:

Group that user will be removed from

sNewGroup:

Group that user will be added to


ContinueLogin()

This method may be called when a new version of the client is available after the OnAutoUpdate event is fired.

When a client update is not mandatory, this method must be called to continue the login process.

CreateChatSession()

This creates a unique chat session and associates it with a chat window.

DetectHTTPProxy()

This function attempts to detect the HTTP proxy and upon success, sets the HTTP proxy address and port. The parameter bRet signals whether the detection succeeded or not. Call GetHttpProxyAddr and GetHttpProxyPort to get the IP address and port of the HTTP proxy if the detection succeeded.

Even though detecting the HTTP proxy sets the HTTP proxy address, it does not start the detection of the firewall. Therefore, it should be called before the final server is set within SetNATTraversalServer.


DownloadAvatar(sUserId, sDirectory)

This function starts downloading of avatar of the logged in user or another buddy. OnAvatarDownloaded event is fired when download completes.

sUserId:

Empty if the logged in user's avatar is to be download or the remote user ID of whom the avatar is to be downloaded

sDirectory:

The directory path where the avatar will be downloaded


GetAllowList()

This returns all user IDs in the current user’s allow list as a VB array. Remote users in the allow list are authorized to receive notifications when the presence information of the current user is updated.

GetBlockList()

This returns all user IDs in the current user’s block list as a VB array.

GetChatSessionParticipants(nSessionId)

This retrieves the current list of participants for a text chat session. A text chat session is identified by the session ID. This returns a VB array containing the list of user IDs of participants in the session. Eyeball Messenger SDK adds each sender and recipient of chat messages and removes each user that exits the chat session. The list excludes the local user.

sSessionId:

Chat session ID

GetContactGroupList(sUserId)

This returns groups that the specified user belongs to as a VB array. The user may belong to more than one group.

sUserId:

User ID of contact

GetContactList()

This returns all user IDs in the current user’s contact list as a VB array. This method should be invoked when an OnUpdateContactList event is received.


GetContactListInGroup(sGroup)

This returns all user IDs in the current user’s contact list belonging to specified group as a VB array.

sGroup:

Group that contacts belonging to will be listed in

GetContactResource(sUserId)

This returns the resource of a specified user as a VB array. A contact may have multiple resources with each entry containing a different resource. Each entry (resource) contains seven elements.

Element Description

Element 1 (Resource name, String): Resource name

Element 2 (State, String): String describing user state

Element 3 (Status description, String): String describing user status

Element 4 (Avatar, String): String describing avatar

Element 5 (Video support, Boolean): Indicates whether video is supported

Element 6 (Audio support, Boolean): Indicates whether audio is supported

Element 7 (Message acknowledgement support, Boolean):

Indicates where message acknowledgement is supported

sUserId:

User ID of contact

GetHttpProxyAddr()



GetHttpProxyDomain()

This returns a case-sensitive HTTP proxy domain. This is valid only for NTLM authentication.


GetHttpProxyPort()

This function returns the HTTP proxy port.


GetHttpProxyPassword()

This function returns the HTTP proxy password that was set by invoking the SetHttpProxyAuthentication method.

GetHttpProxyUserName()

This function returns the HTTP proxy user name that was set by invoking the SetHttpProxyAuthentication method.

GetPresenceState();

This retrieves the state of the user logged in. Standard XMPP states are returned.

GetPresenceStatus();

This retrieves the status of the user logged in.

GetTransferFile(nFileId)

This returns the file name of the file transfer in process. For the sender, the file name includes the full path. Before file transfer is accepted, this function returns only the file name (excluding path) being sent from the receiver. After the file transfer is accepted, this function returns the file name (including path) of the file being saved.

nFileId:


File ID of the file transfer


GetTransferPartner(nFileId)

This returns the user ID of the file transfer partner.

nFileId:



GetTransferProgress(nFileId)

This returns the file transfer progress as a percentage.

nFileId:



GetTransferState(nFileId)

This returns the transfer state of the file transfer as a string. The following transfer states are possible: "error," "request rejected," "aborted," "request sent," "request received," "request accepted," "connecting to sender," "connecting to receiver," "receiving," "sending," "receive complete," and "send complete."

nFileId:




IsInbound(nFileId)

This returns whether the current user is the recipient of the file transfer or not.

nFileId:



IsInContactList(sUserId)

This retrieves whether or not the given user is in the current user’s contact list.

sUserId:

User ID of given user

IsLoggedIn()

This returns true if the user is logged into the XMPP service.

Login(sUserId, sPassword, sResource)

This is the login to the XMPP server using specified ID, password, and resource. Resource is ignored if IgnoreResource property is set to true. Login is a non-blocking process. OnLoginResponse event is fired when the login is concluded (successful or unsuccessful).

sUserId:

User ID for login

sPassword:

User password

sResource:


User resource

Logout()

This is the logout from the XMPP service.

RemoveBlock(sUserId)

This removes a given user from the block list.

sUserId:

User ID of given user to unblock

RemoveContact(sUserId)

This removes a specified user from the current user’s contact list.

sUserId:

Remote user ID to be removed from the contact list

RemoveContactGroup(sUserId, sGroup)

This removes a user from a specific group. The user may belong to more than one group. When no user belongs to a group, the group will be deleted.

sUserId:

User ID to be removed from a group

sGroup:

Group that the user will be removed from


RemoveOfflineMessage(sUserId, nMessageId)

This removes a specific offline message from the server. This method is only relevant for XMPP servers that support OnOfflineMessageHeadline event.

XMPP servers that support offline messages can be classified into 2 types: (1) servers that send all offline messages to the client automatically after login, and (2) servers that only send a message to the client notifying availability of offline messages upon login. For the latter type, Eyeball Messenger SDK fires the event OnOfflineMessageHeadline upon reception of this notification. In this sense, type 1 XMPP servers do not support the OnOfflineMessageHeadline event, and type 2 servers support the OnOfflineMessageHeadline event. For both types of servers, the application program needs to handle all OnOfflineMessage events, one for each incoming message. However, an application for type 2 servers also needs to perform 2 extra steps: call RetrieveOfflineMessage() to request delivery of offline messages upon reception of the OnOfflineMessageHeadline event, and call RemoveOfflineMessage() to remove offline messages from the server. sUserId:

User ID of sender

sMessageId:

Message ID to be removed

RetrieveContactProfile(sUserId)

This retrieves profile information of a specific user. The OnContactProfile event will be fired when profile information is available.

sUserId:

User ID

This is not applicable to the Android or iOS environments.

RetrieveOfflineMessage(sUserId)

This retrieves an offline message sent by a specified user. This requests the server to deliver all offline messages from this user, and an OnOfflineMessage event will be fired upon reception of each offline message.


This method is only relevant for XMPP servers that support the OnOfflineMessageHeadline event, and it should only be called after receiving an OnOfflineMessageHeadline event.

sUserId:

User ID of sender

RetrievePrivateData(sName, sNameSpace)

This retrieves private data stored on the server. The event OnPrivateDataRetrieved will be fired when data is retrieved.

sName:

User-defined private data name

sNameSpace:

User-defined private data name space

SendChatMessage(nSessionId, sUserId, sMsg)

This sends a text message to a remote user. The text chat session is identified by the session ID.

nSessionId:

Session ID for message

sUserId:

Remote user ID to whom message is sent

sMsg:


It returns the ID of the chat message sent which can be used to check if the message has been delivered in the OnChatMessageAcknowledged event.


SendChatMessageHTML(nSessionId, sUserId, sMsg, sHTML)

This sends a text message to a remote user. The text chat session is identified by the session ID. This method also allows sending of HTML text using the sHTML parameter. This parameter is optional, but when it is used, this HTML text must follow the draft specified in http://www.w3.org/1999/xhtml. The message recipient receives both the plain text and the HTML text.

nSessionId:


sUserId:

Remote user ID to whom message is sent

sMsg:


sHTML:

Optional HTML text to be sent, which must follow the draft http://www.w3.org/1999/xhtml when specified. This parameter must include a <body> tag, and it cannot include the <html> tag, e.g. “<body>test message</body>”.

SendEmotiphon(nSessionId, sUserId, sEmotiphon)

This sends an emotiphone message to a remote user. An emotiphone message can be an arbitrary string. The text chat session is identified by the session ID.

nSessionId:


sUserId:

Remote user ID to whom emotiphone message is sent

sEmotiphon:

Emotiphone message to be sent

http://www.w3.org/1999/xhtml




SendExitChat(nSessionId, aUserId)

This is a request to leave a multiparty group chat session. Information is sent to all participants to remove the current user from the list of multiparty chat participants.

nSessionId:


aUserId:

VB array containing chat session participants

SendFile(sUserId, sFileName)

This sends a file transfer request and returns the file ID of the sent file. A standard open file dialog will pop up for choosing a file if the file name specified is empty. Multiple concurrent file transfers are possible. In order to work correctly through NATs and firewalls, the STUN servers must be set (see SetNATTraversalServer below).

sUserId:

Remote user ID to whom file transfer request is sent

sFileName:

File name to be sent


SendMulticastMessage(nSessionId, aUserId, sMsg)

This sends a text message to multiple users. The text chat session is identified by the session ID. The user list is a VB array containing user IDs maintained by the application.

nSessionId:



aUserId:

VB array containing message recipients

sMsg:


SendMulticastMessageHTML(nSessionId, aUserId, sMsg, sHTML)

This sends a text message to multiple users. The text chat session is identified by the session ID. The user list is a VB array containing user IDs maintained by the application. This method also allows the sending of HTML text using the sHTML parameter.

This parameter is optional, but when it is used, this HTML text must follow the draft specified in http://www.w3.org/1999/xhtml. Message recipients receive both the plain text and the HTML text.

nSessionId:


aUserId:

VB array containing message recipients

sMsg:


sHtml:

Optional HTML text to be sent, which must follow the draft http://www.w3.org/1999/xhtml when specified. This parameter must include a <body> tag, and it cannot include the <html> tag, e.g. “<body>test message</body>”.

SendPresence(sUserId)

This sends all presence information (status, state, avatar, audio/video capability, etc.) to a specific user.




sUserId:

User ID

SendPresence2(sUserId, sState, sStatus)

This sends custom presence state and status to a specific user only. This method will not change the current presence state or status of the current user. Unlike the method SendPresence, this method does not send other information, e.g. Avatar, audio, and video capability.

sUserId:

User ID

sState:

User state to be sent to the specified user only (away, chat, dnd and xa)

sStatus:

User status to be sent to the specified user only

SendTypingEvent(nSessionId, sUserId, bStart)

This sends typing indication in a text chat session to a specific user. If user is in a multiparty chat, this method must be called separately with each participant. This method and corresponding notification event is only used to pass the typing event. It is up to the application to detect whether user is typing or not.

nSessionId:


sUserId:

Remote user ID

bStart:

Set to true when user starts typing and set to false when user stops typing


SendXML(sMsg)

This sends a raw XML message to the server. This is an advanced feature. The message to be sent must follow the specification in the XMPP RFC.

sMsg:

Raw XML message to be sent

SetAudioSupport(bSupported)

This informs the remote users on the contact list whether or not the current user is audio capable.

bSupported:

True if current user supports audio

SetAvatar(sImagePath)

This function sets the avatar for the logged in user. The avatar is stored in the server. The image resolution should be in 96 x 96 pixels and the size must be less than 8 KB.

sImagePath:

The full path of the image file including the extension

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 an authentication failure, the event OnLoginResponse is fired with the reason for the failure.



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. The firewall detection will start after all servers have been set.


eServerSRV

This is the DNS SRV domain name that is used to locate the XMPP, STUN, TURN, and STUN-Relay/TURN servers. The port parameter for the server type is ignored.


_xmpp-client._tcp.<srvdomain>XMPP server

_stun._udp.<srvdomain>STUN server (UDP)

_turn._udp.<srvdomain>STUN-Relay/TURN server (UDP)

_turn._tcp.<srvdomain>STUN-Relay/TURN server (TCP)


eServerStunUdp* The UDP STUN server

eServerTurnUdp* The UDP STUN-Relay/TURN server

eServerTurnTcp* The TCP STUN-Relay/TURN server



SetPresence(sState, sStatus)

This sets the presence state and status of the logged in user. The standard XMPP presence states are used.

sState:

User state to be set (away, chat, dnd, xa and unavailable)

sStatus:

User status to be set

SetServer(sServerAddr, nPort)

This sets the address and port of the XMPP server. This value will be used if the DNS SRV query (see SetNATTraversalServer) fails or the DNS SRV domain is not set.

sServerAddr:

Address of XMPP server

nPort:

Port of XMPP server

SetTURNUsernamePassword (sUsername, sPassword)

This sets the authentication information for the TURN server.

sUsername:

Username of the TURN server

sPassword:

Password of the TURN server



SetVideoSupport(bSupported)

This informs remote users on the contact list whether or not the current user is video capable.

bSupported:

True if current user supports video

SetXmppEventHandler(xmppEventHandler)

This sets the event handler class for handing events from the XmppComm control. This class must implement the XmppEventHandler interface.

xmppEventHandler:

An object which implements XmppEventHandler



StorePrivateData(sName, sNameSpace, sData)

This stores private data on the server.

sName:

User-defined private data name

sNameSpace:

User-defined private data name space

sData:

Private data


TransportMode(sMode)

This sets the transport mode as a string. Possible parameters are “TCP” and “TLS”. If “TCP” is selected, the control tries to connect to the XMPP server using TCP (default) and if TCP fails, HTTP tunnelling of the HTTP proxy is set. Transport mode “TLS” causes Eyeball Messenger SDK to use TLS (or TLS through HTTP tunnel) to connect the XMPP server. The transport mode string is case-insensitive.

XmppCommInit

This initializes the XmppComm control.




Notification Events

The following notification events are supported by the XmppCommCtl object:


1 OnLoginResponse

2 OnUpdateContactList

3 OnAddContactRequest

4 OnUpdateMyResource

5 OnUpdateContactState

6 OnConnectionLost

7 OnChatMessage

8 OnUpdateBlockList

9 OnMulticastMessage

10 OnOfflineMessage

11 OnOfflineMessageHeadline

12 OnContactProfile

13 OnTypingEvent

14 OnEmotiphonEvent

15 OnHeadlineMessage

16 OnAutoUpdate

17 OnExitChat

18 OnPrivateDataRetrieved

19 Reserved

20 OnFileTransferRequest

21 OnFileTransferUpdate

24 OnXML


25 OnUpdateMyNickname

26 OnUpdateContactNickname

27 OnChatMessageAcknowledged

28 OnAvatarDownloaded

OnLoginResponse(nResponse)

This fires when the XMPP login process is concluded.

nResponse is an Integer containing a login response code:

Code Description

0: Logged in

1: Time out

2: Account not found

3: Wrong account

4: Account disabled

5: Wrong server configuration

6: Proxy authentication error (basic authentication failed)

7: Proxy authentication error (NTLM authentication failed)

8: HTTP proxy connection failure

9: NTLM domain is empty

Other: Login failed, unknown reason

OnUpdateContactList()

This fires when the contact list has been changed by adding, removing, blocking, or unblocking contacts. Upon receiving this event, the application programmer should invoke the GetContactList method to update the contact list.

OnAddContactRequest(sUserId, sNickName)

This fires when there is an incoming add-contact request. The AddContactResponse method should be invoked to respond to this request.

sUserId:


User ID of the user who sends the add-contact request

sNickName:

User nickname of the user who sends the add-contact request

OnUpdateMyResource()

This fires when the user logs in/out with a different resource.

OnUpdateContactState(sUserId, sState)

This fires when the contact state is changed.

sUserId:

User ID of the contact whose state is updated

sState:

New state of contact

OnConnectionLost()

This fires when the connection to the XMPP server is lost.

OnChatMessage(aMessage)

This fires when there is an incoming chat message.

aMessage is a VB-array containing the following elements:

Element Description

Element 1 (Session ID, Integer): Chat session ID

Element 2 (Sender, String): Message sender


Element 3 (Text, String): Message in plain text

Element 4 (Text, String): Message in HTML

OnUpdateBlockList()

This fires when a block list has been changed by blocking or unblocking contacts. Upon receiving this event, the application programmer should invoke the GetBlockList method to update the block list.

OnMulticastMessage(aMessage)

This fires when there is an incoming multicast chat message.

aMessage is a VB-array containing the following elements:

Element Description



Element 3 (Text, String): Message in plain text

Element 4 (Text, String): Message in HTML

Element 5 (Participant list size, Integer): Number of participants

Subsequent elements in the array contain chat participants – the number of participants is specified above. Each element specifies the User ID of a chat participant.

Android:

OnMulticastMessage(int nSessionID, String strSender, String strMsg, String

strHtml, int nParticipants, String[] participants)

iOS, Mac OS X: OnMulticastMessage(int nSessionID,const std::string &strSender,const

std::string &strMsg,const std::string &strHtml,int nParticipants,const

std::vector<std::string>& participants)

participants:

List of chat participants


OnOfflineMessage(aMessage)

This fires when an offline message is received from a specific user.

aMessage is a VB-array containing two entries. The first entry is the message sender. The second entry is the text message.

Element Description


Element 2 (Message, String): Text message

Each text message contains three elements:

Element Description

Element 1 (Message ID, Integer): Message ID

Element 2 (Time, String): Message time (XEP-0082)

Element 3 (Text, String): Message

OnOfflineMessageHeadline(aHeadline)

This fires automatically after login to notify the current user of the availability of one or more offline messages. This event is not relevant for XMPP servers that automatically send all offline messages to the client after login.

aHeadline is a VB array containing several entries. Each entry has two elements:

Element Description

Element 1 (User ID, String): Remote user ID who sent offline messages

Element 2 (Number, Integer): Number of offline messages from remote user

When this event is fired, the RetrieveOfflineMessage() method can be called to receive messages.

OnContactProfile(aProfile)

This fires when the user profile is available.

aProfile is a VB-array containing the following entries:

Element Description



Element 1 (User ID, String): User ID

Element 2 (First name, String): First name of user

Element 3 (Middle name, String): Middle name of user

Element 4 (Last name, String): Last name of user

Element 5 (City, String): City of user

Element 6 (State, String): State of user

Element 7 (Country, String): Country of user

Element 8 (Marital status, String): Marital status of user

Element 9 (Gender, String): Gender of user

Element 10 (Occupation, String): Occupation of user

Element 11 (Hobbies, String): Hobbies of user

Element 12 (Quote, String): Quotes for user

OnTypingEvent(aTyping)

This fires when a typing indication message is received from a specific user.

aTyping is a VB-array containing three elements:

Element Description

Element 1 (Session ID, Integer):

Session ID

Element 2 (From, String): User who sent the event

Element 3 (Start, Boolean): Set to one when user starts typing and set to zero when user stops typing

OnEmotiphonEvent(aEmotiphon)

This fires when there is an incoming emotiphone message.

aEmotiphon is a VB-array containing the following elements:

Element Description



Element 3 (Text, String): Emotiphone message



OnHeadlineMessage(sMessage, sHtmlMessage)

This fires when there is an incoming headline message. Headline messages are most likely generated by some automated service and no response is expected from the user.

sMessage:

Plain text message

sHtmlMessage:

HTML message

OnAutoUpdate(aUpdate)

This fires when there is an available update for a client. The client must set the version number before login.

aMessage is a VB-array containing four elements:

Element Description

Element 1 (Priority, String): Update priority, one of mandatory, optional or none.

Element 2 (Type, String): Update type, one of full, patch or none.

Element 3 (URL, String): URL of update

Element 4 (Description, String): Description of update

OnExitChat(aInfo)

This fires when someone exits a multiparty chat.

aInfo is a VB array containing two elements:

Element Description


Element 2 (User ID, String): User exiting multiparty chat


OnPrivateDataRetrieved(aData)

This fires when private data is retrieved.

aData is a VB array containing three elements:

Element Description

Element 1 (Name, String): Name of the data

Element 2 (Name space, String): Name space for data

Element 3 (Data, String): Data

OnFileTransferRequest(nFileId)

This fires when there is an incoming file transfer request. AcceptFileTransfer() method must be called to reply to file transfer request.

nFileId:

File transfer ID


OnFileTransferUpdate(nFileId)

This fires when there is file transfer status update. GetTransferState() method may be called to retrieve file transfer state.

nFileId:

File transfer ID


OnXML(sMsg)

This fires whenever an XML message is received from the server.


sMsg:

Raw message received

OnUpdateMyNickname(sNickname)

This fires when the user’s nickname is changed. For example, when a user logs in and has not set the Nickname property, but a nickname has been retrieved from the server, this event will be fired. The new nickname is returned by this event, but it can also be retrieved using the Nickname property.

sNickname:

New nickname of the user

OnUpdateContactNickname(sUserId, sNickname)

This fires when the contact’s nickname is changed.

sUserId:

User ID of the contact whose nickname is updated

sNickname:

New nickname of the contact

OnChatMessageAcknowledged(nChatMessageId)

This fires when the remote buddy acknowledges the reception of the sent chat message.

nChatMessageId:

The chat message ID of the received message

OnAvatarDownloaded(sUserId, sImagePath)


This fires when download of an avatar of the logged in user or a buddy completes.

sUserId:

Empty if the downloaded avatar is of the logged in user or the remote buddy's user ID

sImagePath:

The full path of the downloaded avatar


7.4. Messenger SDK: Error Handling

Error Handling

XmppCommCtl returns the error codes 0x80004005 (in hexadecimal format) as well as error descriptions for all errors. These errors are thrown as exception in JScript. The following sample code shows how to handle these errors in JScript:

try

{

XmppCommCtl.Call(sRemoteURI);

}

catch(e)

{

alert(“Error description:” + e.description);

}

Android:

XmppCommOnError(String sError) event is fired.

iOS, Mac OS X:

OnError(const string &sError) event is fired.


8. Messenger SDK: Video Windows - Windows SDK

Video Windows - Windows SDK

The Video Window ActiveX control is used as a placeholder for video windows. It can be instantiated in a web page as follows: <OBJECT

id="VideoWindowCtl"

classid="CLSID: 0504639F-FBD4-4272-B232-AB9B21305618">

</OBJECT>

The VideoWindowCtl object supports one single interface: IVideoWindow. Properties, methods, and events of the control are described in details below.

Properties

VideoWindowCtl.BgColor

This specifies the background color of control as a string. This color is displayed when no video is attached to the window. The default background color is black. Common Windows color string or RGB string like “#RRGGBB” (for example, “00A5EF”) may be assigned.

Methods

nWnd = VideoWindowCtl.GetVideoWindow()

This retrieves a handle to the video window. The return value can be passed to the AttachVideoWindow method in SipCommCtl.


9. Messenger SDK: Video Windows - Android SDK

Video Windows - Android SDK

There will be two kinds of view for displaying video – VideoRecordView for displaying self-camera preview window and GLVideoPlayView for displaying remote video window. Both have to be declared in an xml file.

<com.eyeball.sipcontact.GLVideoPlayView />

<com.eyeball.sipcontact.VideoRecoredView />


Properties, methods, and events of the control are described in details below.

Methods

SipJniWrapper.SipCommChangeCameraParameters(int nFrameRate, int nBitRate, int

nKeyFrameInterval, int nRotateAngle)

This is called for changing camera capture parameters.

Parameter Description

nFrameRate Unused, must be -1.


nBitRate Unused, must be -1.

nKeyFrameInterval Unused, must be -1.

nRotateAngle Rotation angle in degrees at which the camera data should be rotated after capture. Can be 0, 90, 180 or 270.

SipJniWrapper.JChangeCameraParameters(int nFrameRate, int nBitRate, int


This is called for changing camera display parameters.





nRotateAngle Rotation angle in degrees at which the camera preview should be displayed. Can be 0, 90, 180 or 270.

SipJniWrapper.ChangeCameraParameters(int nFrameRate, int nBitRate, int


This is called for changing Camera Parameters.





nRotateAngl Rotation angle in degrees for self video to be rotated. Can be 0, 90, 180 or 270.

Notification Events

SipCommOnVideoSizeChange(int nWidth, int nHeight)

This fires when remote video size is changed. It includes the width and height of the remote video.


10. Messenger SDK: Audio Wizard - Windows SDK

Audio Wizard - Windows SDK

Audio Wizard ActiveX control is used for audio playback and capture tuning. It can be instantiated in a web page as follows:

<OBJECT

id="AudioWizardCtl"

classid="CLSID: A1B1AE18-9D2A-4861-AC13-52FBCB43BBC8">

</OBJECT>

The AudioWizardCtl object supports one single interface IAudioWizard. Properties, methods, and events of the control are described in details below.

Properties

AudioWizardCtl.CaptureDeviceIndex

This sets a preferred audio capture device by index or retrieves the index of the device in use as an integer. Index is zero-based.

AudioWizardCtl.PlaybackDeviceIndex


This sets a preferred audio playback device by index or retrieves the index of the device in use as an integer. Index is zero-based.

AudioWizardCtl.MicrophoneVolume

This sets or retrieves the microphone volume level. The value ranges from 0 (off) to 65535 (full volume).

AudioWizardCtl.WaveVolume

This sets or retrieves the wave volume level. The value ranges from 0 (silent) to 65535 (full volume).

AudioWizardCtl.PlayWhileCapture

This sets or retrieves whether or not to play audio while capturing. This is a Boolean property.

Methods

aDeviceName = AudioWizardCtl.GetCaptureDeviceName();

This returns the audio capture device name as a VB array. Each entry contains a single element: the text description of the audio capture device.

aDeviceName = AudioWizardCtl.GetPlaybackDeviceName();

This returns the audio playback device name as a VB array. Each entry contains a single element: the text description of the audio playback device.

AudioWizardCtl.StartCapture();

This starts capturing audio.

AudioWizardCtl.StopCapture();


This stops capturing audio.

nEnergy = AudioWizardCtl.GetCaptureEnergy();

This returns the energy of the audio captured. Energy is calculated over time when capture is started. The value is in the range 0 to 65535.

AudioWizardCtl.StartPlay(sFileName, bLoop);

This starts playing the audio file from disk.

sFileName:

This is the file name to be played. It can be any audio file (mp3, wave, etc).

bLoop:

Set to true in order to start playing the file from the beginning when ended.

AudioWizardCtl.StopPlay();

This stops playing the audio invoked by StartPlay.

AudioWizardCtl.StartPlay2(sFileName, bLoop, iVolume);

This starts playing an audio file from disk. Playback volume can also be specified.

sFileName:

This is the file name to be played. It can be any audio file (mp3, wave, etc).

bLoop:

Set to true in order to start playing the file from the beginning when ended.

iVolume:

Volume used for playback; this value is in the range 0 to 65535.


AudioWizardCtl.StopPlay2();

This stops playing the audio invoked by StartPlay2.

Notification Events

The following notification events are supported by AudioWizardCtl object:


1 OnMicrophoneVolumeChange

2 OnWaveVolumeChange

OnMicrophoneVolumeChange()

This fires when the microphone volume is changed.

OnWaveVolumeChange()

This fires when the playback volume is changed.


11. Messenger SDK: Federated IM - Windows SDK

Federated IM - Windows SDK

The FedIM ActiveX control provides access to IM services such as Yahoo, GoogleTalk, ICQ, MSN, and AOL and supports the following features:

The following HTML code embeds the FedIMControl ActiveX object into a web page:

<OBJECT

id="FedIMControl"

classid="CLSID: D096B9A6-64BF-4581-B9E8-2CD5C8C53AA5">

</OBJECT>

11.1 Messenger SDK: Properties




11.1 Messenger SDK: Properties

Properties

FedIMControl.KeepAlivePeriod

This sets the keep-alive timer value in seconds. This can be used to ensure HTTP proxy connections are not closed. The default value is 30 seconds.



Methods

FedIMControl.Login(sUserName, sPassword, sService);

This logs sUserName into the server for the sService.


sUserName: User name

sPassword: Password of the usersUserName

sService: This is the IM service (Yahoo!, MSN, Google Talk, AOL, ICQ) the client wants to log into. This is case-sensitive.

FedIMControl.Logout(nHandle);

This logs out from the service.


nHandle: This is the handle of the client that wants to logout. Every client is identified with a unique handle (returned by OnSessionConnectSuccess).

FedIMControl.GetHttpProxyAddr(sProxyAddress);



FedIMControl.GetHttpProxyPort(nPort);

This function returns the HTTP proxy port.

FedIMControl.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 OnConnectFailure event is fired with the reason for the failure.


FedIMControl.GetHttpProxyUserName();

This function returns the HTTP proxy user name that was set by invoking SetHttpProxyAuthentication method.

FedIMControl.GetHttpProxyPassword();

This function returns the HTTP proxy password that was set by invoking SetHTTPProxyAuthentication method.

FedIMControl.DetectHttpProxy(bRet);

This function attempts to detect the HTTP proxy and upon success sets the proxy server address and port. The parameter bRet signals whether the detection succeeded or not. Call GetHttpProxyAddr and GetHttpProxyPort to get the IP address and port of the proxy if the detection succeeded. Even though detecting the HTTP proxy sets the HTTP proxy address, it does not start the detection of the firewall. Therefore, it should be called before the final server is set within SetNATTraversalServer.


FedIMControl.TransportMode(sMode);

This is an advanced setting only valid for GoogleTalk. By default, it is set to “AUTO” and should not be modified. This method sets or retrieves the transport mode as a string. The transport mode can be “TCP” or “HTTP” or “AUTO”. If “HTTP” was selected, the control tries to connect to the federated IM server using the IP address given by SetServer with port 443. If “AUTO” was selected, the control tries to connect to the Federated IM server using TCP (default) and – if TCP fails - HTTP tunneling if the HTTP proxy was set.

The transport mode string is case-insensitive.

FedIMControl.SetSeparatorString(sSeparatorString);

By default, the buddy list received via OnBuddyListReceive uses “:” as a separator token.

That means the string is formatted as follows: “+Group1

Userid1 : Displayname1 : Status1


+Group2


+Group3


Userid5 : Displayname5 : Status5”

The separator ":" can be replaced with this method. If the parameter is empty or the function is not called, the default ":" will be used.

FedIMControl.SendTextMessage(nHandle, sTargerUser, sMessage);

This sends sMessage to sTargetUser from the user identified by nHandle.



nHandle: Handle of the sender client.

sTargetUser: User ID that will receive the text message.

sMessage: This is the text message.

FedIMControl.SetStatus(nHandle, sStatus, bAway);

This changes the user’s presence status text.


nHandle: Handle of the client.

sStatus: New status text.

bAway: If this value is true then Yahoo! users see user status as away.

The services support different presence status messages as described below.

Google Talk supports the status texts “away”, “dnd” and “chat” (case-sensitive). In addition to each of those basic status messages, Google Talk allows to add an additional custom status.

For example, in order to set a custom available status as “Googling”, the status text should be “chat + Googling”. In order to set the custom available status as “Available”, the status text will be “chat + Available”. In order to set a custom busy status “Googling”, the status text “dnd + Googling” can be used. All of these status texts are case-sensitive and the custom text is separated by “+.”

AOL/ICQ supports the status texts “Available”, “Away”, “Online”, and “Invisible” (case-sensitive). Other status messages are not supported.

MSN supports the status texts “Available”, “Away”, “Busy”, and “Invisible”. Any other text will be interpreted as “Away”.

Yahoo! supports the status texts “Available”, “BRB”, “Busy”, “Not Home”, “Not at Desk”, “Not in Office”, “On Phone”, “On Vacation”, “Out to Lunch”, “Stepped Out”, “Invisible”, “Idle”, and “Offline” (case-sensitive). In addition, any custom status texts can be defined. When using SetStatus to set a custom status, the Yahoo! service first sets the status text to “Available” and then changes the status text to the custom string.

FedIMControl.AcceptNAddBuddy(nHandle, sBuddy, sGroup);


This accepts an add request and adds the contact to a group.


nHandle: Client handle

sBuddy: Contact name

sGroup: Name of the group to add the contact to

FedIMControl.AddBuddy(nHandle, sBuddyID, sBuddyGroup, sMessage);

This adds a contact to the contact list.


nHandle: Handle of the client

sBuddyID: The ID of the contact to add

sBuddyGroup: The group name where this new contact will be added

sMessage: This message will be sent to the user with add request (sMessage is only valid for Yahoo! users)

FedIMControl.RemoveBuddy(nHandle, sBuddyID, sBuddyGroup);

This removes a buddy from the contact list.



sBuddyID: The ID the client wants to remove

sBuddyGroup: The group name from which this new buddy will be removed


FedIMControl.IgnoreBuddy(nHandle, sBuddyID);

This ignores or blocks a buddy.



sBuddyID: The ID of the buddy that the client wants to ignore

FedIMControl.UnignoreBuddy(nHandle, sBuddyID);

This un-ignores or unblocks a buddy.



sBuddyID: The ID of the buddy that the client wants to un-ignore/unblock

FedIMControl.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.



eServerSRV

This is the DNS SRV domain name that is used to locate the XMPP, STUN, TRUN and STUN-Relay/TURN servers. The port parameter for the server type is ignored.


_turn._tcp.<srvdomain>STUN-Relay/TURN server (TCP)


eServerStunRelayTcp* The TCP STUN-Relay/TURN server


FedIMControl.SetTURNUsernamePassword(sUsername, sPassword);

This sets the authentication information for the TURN server.


sUsername: Username of the TURN server

sPassword: Password of the TURN server


FedIMControl.SendTyping(nHandle, sTo, nStatus);

This sends the typing notification status to the user identified by string sTo.



sTo: Contact ID that will receive typing information

nStatus: 0 means end typing; 1 means typing


Typing notifications are not supported for Google Talk in this version. MSN does not support sending end typing notifications. Eyeball Messenger SDK will generate an exception if you try to send an end typing notification for MSN.

FedIMControl.RejectBuddy(nHandle, sBuddy, sMessage);

This rejects an add request from the contact given in sBuddy.



sBuddy: Whom you want to reject

sMessage: Optional text message valid for Yahoo! only

This method is valid for Yahoo!, MSN, and Google Talk. ICQ and AOL do not support explicit rejection of add requests. Eyeball Messenger SDK will generate an exception when used with ICQ or AOL. Instead, add requests in ICQ or AOL should be ignored.

FedIMControl.SetStealth(nHandle, sBuddy, nAdd);

This adds or removes the contact to the stealth list.



sBuddy: Contact name

nAdd: If this value is 0 then the contact will be removed. If it is 1 then the contact will be added to the stealth list.

This method is only valid for Yahoo!



Notification Events

The following notification events are supported by the FedIMControl object:


9: OnSessionConnectSuccess

10: OnSessionConnectFailure

11: OnSessionMessageReceive

12: OnSessionDisconnected

13: OnSessionBuddylistReceive

14: OnSessionBuddyAdded

15: OnSessionBuddyAddFailed

16: OnSessionBuddyRemoved

17: OnSessionBuddyRemoveFailed

27: OnMailNotification

29: OnSessionIgnorelistReceive

30: OnSessionBuddyStatusChanged

31: OnRemoteUserTyping

32: OnAddUserRejected

33: OnAddUserRequest

34: OnStealthList

OnSessionConnectSuccess(aInfo)


This fires when the client successfully connects to FedIM Accounts.


Element Description

Element 1 (Client Handle, Integer):

This returns the handle of the client. The handle value is now constant:

Yahoo!: 1

MSN: 2

AOL: 3

ICQ: 4

GoogleTalk: 5

Element 2 (User ID, String): User ID of the client

Element 3 (FedIM Account, String):

The FedIM account name that the client is logged into

OnSessionConnectFailure(aInfo)

Fires when client fails to connect to FedIM accounts.


Element Description

Element 1 (Client Handle, Integer): Temporary client handle

Element 2 (User ID, String): User ID of the client

Element 3 (FedIM Account, String): The FedIM account name that the client is logged in to

Element 4 (Reason Phrase, String): The reason of connection failure

OnSessionMessageReceive(aMessageInfo)

This fires when a text message is received.

aMessageInfo is a VB-array containing following elements:

Element Description

Element 1 (Client Handle, Integer): Temporary client handle


Element 2 (Receiver Name, String): This represents the message receiver user ID

Element 3 (Sender Name, String): This is the ID of the text sender

Element 4 (FedIM Account, String): This is the FedIM Account name of the sender and receiver

Element 5 (Message, String): The text message

OnSessionDisconnected(aResponseInfo)

This fires when a client gets disconnected from the FedIM account.

aResponseInfo is a VB-array containing following elements:

Element Description

Element 1 (Client Handle, Integer): Handle of the disconnected client

Element 2 (User ID, String): User ID of that client

Element 3 (FedIM Account, String): The FedIM Account the client was logged into

Element 4 (Reason Phrase, String): The reason for disconnection

OnSessionBuddylistReceive(aBuddyList)

This fires after the client logs in. The buddy list from the server is received in this event.

aBuddyList is a VB-array containing following elements:

Element Description


Handle of the client whose buddy list is updated

Element 2 (User ID, String):

User ID of that client


The FedIM Account the client was logged in to

Element 4 (Buddy list, String):

This is the buddy list.

The format of this string is as follows: buddies are grouped.

The list starts with a group name, which always begins with a “+” character. After the group name, the buddies in this group are listed.

Example: If a buddy list has 2 groups “Group A” and “Group B,” “Group A” contains buddies with ID “A1”, “A2” and “A3,” and “Group B” contains only buddy “B1,” the buddy list string will be:


“+Group A

A1 : Display name of A1 : Presence status



+Group B

B1 : Display name of B1 : Presence status”

When the Federated IM control logs in, the complete buddy list is received via the OnSessionBuddyList event with all buddies marked as offline. After that, the status of each online buddy is updated using the event OnSessionBuddyStatusChanged.

Please note that unless otherwise specified, the default separator string “:” will be used.

OnSessionBuddyStatusChanged(aInfo)

This fires when a buddy changes his/her status.

aInfo is a VB-array containing the following elements:

Element Description

Element 1 (Client Handle, Integer): Handle of the client whose buddy list is updated


Element 3 (FedIM Account, String): The FedIM Account the client was logged in to

Element 4 (Buddystatus, String): The name and presence status of the buddy that changed the status

Format of the buddystatus string:

userid <separator string> displayname <separator string> status

Yahoo! custom status messages that are to be interpreted as busy will be appended with “ + busy”. Google custom status messages are interpreted such as “chat + custom status” and “dnd + custom status.”

Example:

”eyeballtest : eyeballtest displayname : online” , if the separator string

(see SetSeparatorString) is set to the default " : ".


OnSessionBuddyAdded(aInfo)

This fires when a buddy is successfully added to the contact list.


Element Description

Element 1 (Client Handle, Integer): Handle of the client that added the buddy successfully


Element 3 (Buddy ID, String): The added buddy ID

Element 4 (FedIM Account, String): The FedIM Account of the client

OnSessionBuddyAddFailed(aInfo)

This fires when the client fails to add the buddy in his contact list.


Element Description

Element 1 (Client Handle, Integer): Handle of the client that tried to add the buddy


Element 3 (Buddy ID, String): The added buddy ID


Element 5 (Reason Phrase, String): The reason of the failure

OnSessionBuddyRemoved(aInfo)

This fires when a buddy is successfully removed from the contact list.


Element Description

Element 1 (Client Handle, Integer): Handle of the client that removed the buddy successfully


Element 3 (Buddy ID, String): The removed buddy ID



OnSessionBuddyRemoveFailed(aInfo)

This fires when the client fails to remove a buddy from his contact list.


Element Description

Element 1 (Client Handle, Integer): Handle of the client that tried to remove the buddy


Element 3 (Buddy ID, String): The removed buddy ID


Element 5 (Reason Phrase, String): The reason of the failure

OnMailNotification (aInfo)

This fires when the client receives new mail.


Element Description

Element 1 (Client Handle, Integer): Handle of the client that receives the mail


Element 3 (Sender ID, String): The mail sender’s ID


Element 5 (Subject, String): The subject of the mail

When user logs in to Yahoo! or MSN, and the user has new mail message in his inbox then Sender ID will be “New Messages\n” and the subject will be the number of unread new mails.

OnSessionIgnorelistReceive(aInfo)

This fires when the client receives the list of blocked users (ignore list).


Element Description



Handle of the client that receives the ignore list


User ID of the client that receives the ignore list


The FedIM Account of the client

Element 4 (ignorelist, String):

This is the actual list of blocked users. A newline character ‘\n‘ is added after each user in the list. For example:

“[email protected]\n

[email protected]\n

[email protected]\n”

OnRemoteUserTyping(aInfo)

This fires when the remote user starts or stops typing.


Element Description


Handle of the client that receives the notification


User ID of that client

Element 3 (Sender ID, String):

The typing notification sender’s ID


The FedIM Account of the client

Element 5 (Typing Status, String):

This is the typing status.

Possible values are “is typing,” “ends typing,” and “is no longer typing” (case-sensitive, AOL and ICQ only).

Please note that MSN does not send end typing notification. Typing notification for Google Talk is currently not supported.

OnAddUserRejected (aInfo)

This fires when a contact rejects an add request.


mailto:[email protected]




Element Description

Element 1 (Client Handle, Integer): Handle of the client that receives the notification


Element 3 (Sender ID, String): The ID of the contact that rejected the request



This is the text message that the contact sent with the rejection.

This element is valid for Yahoo! only.

OnAddUserRequest (aInfo)

Fires when client receives a contact add request.


Element Description

Element 1 (Client Handle, Integer): Handle of the client that receives the notification


Element 3 (Sender ID, String): The ID of the contact making the add request



This is the text message the contact sent with an add request.

This element is valid for Yahoo! only.

OnStealthList(aInfo)

This event is only fired for Yahoo! accounts. Fires when client receives the stealth list from the server.


Element Description


Handle of the client that receives the notification



The Yahoo! Account of the client


Element 4 (Stealth list, String):

This is the stealth list of accounts. The contact names are separated by “,”.

For example, if only “User A” is in the stealth list, the value of this element will be “User A”.

If “User A” and “User B” are in the stealth list, the value will be “User A, User B”.


12. Messenger SDK: Common Error Codes and Descriptions - Windows SDK

Common Error Codes and Descriptions - Windows SDK

The following error codes and descriptions apply to all ActiveX controls in Eyeball Messenger SDK v8.1 ActiveX library.

Code Description

0x80040000 Unexpected

0x80040001 Not logged in

0x80040002 Already logged in

0x80040003 Server is not properly set or unable to find the DNS server

0x80040004 The control failed to log into the server. Please verify the User ID and password.

0x80040005 Empty User ID

0x80040006 User ID does not exist

0x80040007 No response

0x80040008 Empty file name

0x80040009 Empty text message

0x8004000A Service is not subscribed

0x8004000B Service is not licensed

0x8004000C Failed to open the destination file. Make sure the file is not in use

0x8004000D The specified file does not exist

0x8004000E The video capture device is not working

0x8004000F The audio capture device is not working

0x80040010 The specified user is not online

0x80040011 NULL pointer


13. Messenger SDK: Legal and Contact Information

Legal and Contact Information


Confidential Information: This document contains confidential and proprietary information. The document has been provided to you in your capacity as a customer or evaluator of Eyeball Networks Inc.'s products. Unauthorized reproduction and distribution is prohibited unless specifically approved by Eyeball Networks Inc.

Eyeball, Eyeball.com, its logos, AnyBandwidthTM and AnyFirewall™ are trademarks of Eyeball Networks Inc. All other referenced companies and product names may or may not be trademarks of their respective owners.

For more information visit Eyeball Networks Inc. at http://www.eyeball.com.

Department E-mail

Sales [email protected]

Technical Support [email protected]

Corporate Headquarters:

730 - 1201 West Pender Street

Vancouver, BC V6E 2V2

Canada

Tel. +1 604.921.5993

Fax +1 604.921.5909

http://www.eyeball.com/



eyeball messenger sdk v10.0 developer reference guide

Software

video client

eyeball networks

eyeball messenger sdk

video data

video calls

highquality video

maximum video quality

best possible video