API Reference Guide

AudioCodes WebRTC Solutions for Enterprises

WebRTC Android Client SDK

API Reference Guide
WebRTC Android Client SDK API Contents

Table of Contents
1 Introduction ......................................................................................................... 9
1.1 Purpose ..................................................................................................................9
1.2 Scope .....................................................................................................................9
1.3 Benefits ..................................................................................................................9
2 Android SDK ...................................................................................................... 11
2.1 Before you Start ...................................................................................................11
2.2 Installation ............................................................................................................11
3 API Classes........................................................................................................ 13
3.1 AudioCodesUA .....................................................................................................14
3.1.1 Standard Methods ...................................................................................................14
3.1.1.1 getInstance ...............................................................................................14
3.1.1.2 setServerConfig ........................................................................................14
3.1.1.3 setAccount (1) ..........................................................................................15
3.1.1.4 setAccount (2) ..........................................................................................15
3.1.1.5 setListeners ..............................................................................................15
3.1.1.6 login ..........................................................................................................16
3.1.1.7 logout ........................................................................................................16
3.1.1.8 call ............................................................................................................16
3.1.2 Advanced Methods ..................................................................................................17
3.1.2.1 setRegisterExtraHeaders .........................................................................17
3.1.2.2 setInviteExtraHeaders ..............................................................................17
3.1.2.3 getUserAgent ...........................................................................................17
3.1.2.4 setUserAgent ............................................................................................18
3.1.2.5 getRegExpires ..........................................................................................18
3.1.2.6 setRegExpires ..........................................................................................18
3.1.2.7 setUseSessionTimer ................................................................................18
3.1.2.8 setLogLevel ..............................................................................................19
3.1.2.9 setLogger .................................................................................................19
3.1.2.10 handleNetworkChange .............................................................................19
3.1.2.11 getSessionList ..........................................................................................20
3.1.2.12 setContactRewrite ....................................................................................20
3.2 AudioCodesSession .............................................................................................21
3.2.1 Standard Methods ...................................................................................................22
3.2.1.1 getSessionID ............................................................................................22
3.2.1.2 answer ......................................................................................................22
3.2.1.3 reject .........................................................................................................22
3.2.1.4 Terminate .................................................................................................22
3.2.1.5 muteAudio ................................................................................................23
3.2.1.6 muteVideo ................................................................................................23
3.2.1.7 isAudioMute ..............................................................................................23
3.2.1.8 isVideoMute ..............................................................................................23
3.2.1.9 sendDTMF ................................................................................................24
3.2.1.10 isOutgoing ................................................................................................24
3.2.1.11 hasVideo ..................................................................................................24
3.2.1.12 getCallState ..............................................................................................24
3.2.1.13 getTermination .........................................................................................25
3.2.1.14 duration.....................................................................................................25
3.2.1.15 isLocalHold ...............................................................................................25
3.2.1.16 isRemoteHold ...........................................................................................25
3.2.1.17 setUserData .............................................................................................26
3.2.1.18 getUserData .............................................................................................26

SDK API 3 WebRTC

 API Reference Guide

3.2.1.19 hold ...........................................................................................................26

3.2.1.20 switchCamera ...........................................................................................26
3.2.1.21 showVideo (1) ..........................................................................................27
3.2.1.22 showVideo (2) ..........................................................................................27
3.2.1.23 stopVideo .................................................................................................27
3.2.1.24 setLocalRenderPosition ...........................................................................28
3.2.1.25 addSessionEventListener.........................................................................28
3.2.1.26 removeSessionEventListener ..................................................................28
3.2.1.27 getStats ....................................................................................................29
3.2.1.28 redirect......................................................................................................29
3.2.1.29 reinviteWithVideo .....................................................................................29
3.3 WebRTCAudioManager .......................................................................................30
3.3.1 Standard Methods ...................................................................................................30
3.3.1.1 getInstance ...............................................................................................30
3.3.1.2 setWebRTCAudioRouteListener ..............................................................30
3.3.1.3 setAudioRoute ..........................................................................................31
3.3.1.4 getAudioRoute ..........................................................................................31
3.3.1.5 getAvailableAudioRoutes .........................................................................31
3.4 ACConfiguration ...................................................................................................32
3.4.1 Standard Methods ...................................................................................................33
3.4.1.1 getConfiguration .......................................................................................33
3.4.1.2 version ......................................................................................................33
3.4.1.3 getLocalServerPort ...................................................................................33
3.4.1.4 setLocalServerPort ...................................................................................33
3.4.1.5 getDtmfOptions ........................................................................................34
3.4.1.6 setDtmfOptions .........................................................................................34
3.4.1.7 getVideoConfiguration ..............................................................................34
3.4.1.8 setVideoConfiguration ..............................................................................34
3.4.1.9 setAutomaticCallOnRedirect ....................................................................35
3.4.1.10 getAutomaticCallOnRedirect ....................................................................35
3.4.1.11 setRedirect ...............................................................................................35
3.4.1.12 getRedirectContact...................................................................................36
3.4.1.13 getRedirectEnabled ..................................................................................36
3.5 Video Configuration ..............................................................................................37
3.5.1 Camera Parameters ................................................................................................37
3.5.2 Rendering Views Parameters ..................................................................................37
3.6 DTMF Options ......................................................................................................38
3.6.1 DTMF Parameters ...................................................................................................38
3.7 Remote Contact ...................................................................................................39
3.7.1 Standard Methods ...................................................................................................39
3.7.1.1 getDisplayName .......................................................................................39
3.7.1.2 getUserName ...........................................................................................39
3.7.1.3 getDomain ................................................................................................40
3.7.1.4 setDisplayName .......................................................................................40
3.7.1.5 setUsername ............................................................................................40
3.7.1.6 setDomain ................................................................................................40
4 API Callbacks/ Listeners Interfaces ................................................................. 41
4.1 AudioCodes Event Listener ..................................................................................41
4.1.1 LoginStateChanged .................................................................................................41
4.1.2 incomingCall ............................................................................................................41
4.2 AudioCodes Session Event Listener..................................................................... 42
4.2.1 callTerminated .........................................................................................................42
4.2.2 callProgress .............................................................................................................42
4.2.3 cameraSwitched ......................................................................................................42
4.2.4 reinviteWithvideoCallback........................................................................................43

WebRTC Android Client SDK API 4 Document #: LTRT-14062

WebRTC Android Client SDK API Contents

4.3 Web RTC Audio Route Listener............................................................................ 43

4.3.1 audioRoutesChanged ..............................................................................................43
4.3.2 currentAudioRouteChanged ....................................................................................43
5 Use Examples .................................................................................................... 45
5.1 User Agent: Create Instance, Set Server and Account ......................................... 45
5.2 User Agent: Set Listeners (callbacks) ................................................................... 45
5.3 User Agent login: Connection to SBC server, and Login ....................................... 45
5.4 Make a Call ..........................................................................................................45
5.5 Send DTMF during Call ........................................................................................45
5.6 Mute / Unmute During Call ...................................................................................45
5.7 Accept Incoming Call (with Video) ........................................................................ 45
5.8 Reject Incoming Call.............................................................................................46
5.9 Terminate a Call ...................................................................................................46
5.10 Use of Video .........................................................................................................46

SDK API 5 WebRTC

 API Reference Guide

This page is intentionally left blank.

WebRTC Android Client SDK API 6 Document #: LTRT-14062

WebRTC Android Client SDK API Notices

Notice
Information contained in this document is believed to be accurate and reliable at the time of
printing. However, due to ongoing product improvements and revisions, AudioCodes cannot
guarantee accuracy of printed material after the Date Published nor can it accept responsibility
for errors or omissions. Updates to this document can be downloaded from
https://www.audiocodes.com/library/technical-documents.
This document is subject to change without notice.
Date Published: October-29-2018

WEEE EU Directive
Pursuant to the WEEE EU Directive, electronic and electrical waste must not be disposed of
with unsorted waste. Please contact your local recycling authority for disposal of this product.

Customer Support
Customer technical support and services are provided by AudioCodes or by an authorized
AudioCodes Service Partner. For more information on how to buy technical support for
AudioCodes products and for contact information, please visit our Web site
https://www.audiocodes.com/services-support/maintenance-and-support.

Stay in the Loop with AudioCodes

Abbreviations and Terminology

Each abbreviation, unless widely used, is spelled out in full when first used.

SDK API 7 WebRTC

 API Reference Guide

Related Documentation

Document Name

https://www.audiocodes.com/solutions-products/solutions/enterprise-voice/webrtc-connectivity
WebRTC Client SDK API Reference Guide
WebRTC Click-to-Call Widget Installation and Configuration Guide

Document Revision Record

LTRT Description

14060 Initial document release for Version 1.0

14061 Added functionality for SDK version 1.0.1
14062 • Updated to software version 1.0.6
• Update for new function “setContactRewrite”

Documentation Feedback
AudioCodes continually strives to produce high quality documentation. If you have any
comments (suggestions or errors) regarding this document, please fill out the Documentation
Feedback form on our Web site at https://online.audiocodes.com/documentation-feedback.

WebRTC Android Client SDK API 8 Document #: LTRT-14062

WebRTC Android Client SDK API 1. Introduction

1 Introduction
WebRTC technology enriches user experience by adding voice, video and data
communication to the browser, as well as to mobile applications. AudioCodes WebRTC
gateway provides seamless connectivity between WebRTC clients and existing VoIP
deployments.
A typical WebRTC solution is comprised of a WebRTC Gateway, which is an integrated
functionality on AudioCodes SBCs, and a client application running on a browser or a mobile
app. AudioCodes WebRTC Android client SDK is a Java code based API that allows Android
developers to integrate WebRTC functionality into Android applications for placing calls from
the Android device to the SBC.

Note: For a simple click-to-call button use case, a WebRTC widget is offered which can
be easily integrated into websites and blogs without any JavaScript knowhow. See the
WebRTC Widget Installation and Configuration Guide.

1.1 Purpose
This Reference Guide defines Application Programming Interface (API) use of the Web Real-
Time Communications (RTC) SDK.

1.2 Scope
The guide describes the API that must be implemented to use AudioCodes' WebRTC
Android SDK to build an Android application that will interact with AudioCodes' server to
establish voice and video calls.
The guide may be used by Android developers who want to use the AudioCodes-provided
SDK to build Web RTC clients.

1.3 Benefits
Here's a summary of the benefits:
 Simple deployment - a single WebRTC gateway device for both signaling and media
 Strong security and interoperability capabilities resulting from integration with SBC
 Client SDK for Android application.
 OPUS powered IP phones for superb, transcoder-less voice quality
 Optional recording of WebRTC calls

SDK API 9 WebRTC

 API Reference Guide

This page is intentionally left blank.

WebRTC Android Client SDK API 10 Document #: LTRT-14062

WebRTC Android Client SDK API 2. Android SDK

2 Android SDK
2.1 Before you Start
Here's what you require before you start using the Android SDK:
 Android Studio (tested with Android Studio 3.1)
 Android device with minimum OS 5.0
 Provided with the SDK:
• WebRTC SDK AAR file. This is the WebRTC SDK aar file. The file must be
included in a project in order to use the SDK.
• Android demo client project. This is the Android Studio project that can be
opened from Android Studio. This is a fully working client and shows how to use
the SDK and the aar file.
• Javadocs. Located in the Android demo client. These are javadocs that can used
as a reference to the WebRTC SDK.

2.2 Installation
Here's what you need to do to install the SDK.

 To install the SDK:

1. Install Android Studio
2. Open a project for the demo client
3. Follow instructions from Android Studio (necessary Android SDK files will need to be
downloaded and installed.)
4. Disable instant run in Android Studio. (Android Studio 3.1 has a bug where it will not
compile correctly.)
a. Disable instant run in Android studio because of Android Studio issue:
https://issuetracker.google.com/issues/72811718
5. Make sure the AAR file / module is included (see demo client build.gradle file). For
example
a. implementation project(':webrtcsdk-release')
6. Make sure the WebRTC files are included:
a. implementation 'org.webrtc:google-webrtc:1.0.+'
b. The current WebRTC supported SDK is 1.0.22920
7. The WebRTC SDK is currently required to add the following lines to the application
build.gradle files (see Demo client):
ndk {
//abiFilters 'armeabi', 'armeabi-v7a'
abiFilters 'armeabi-v7a'
}
8. The SDK will need certain Android permissions. The SDK will not check if these
permissions are present for the Android application. Any Android application that uses
the SDK will need to make sure the permission is requested and provided by the user.
The demo client provides examples on how to do this.

SDK API 11 WebRTC

 API Reference Guide

This page is intentionally left blank.

WebRTC Android Client SDK API 12 Document #: LTRT-14062

WebRTC Android Client SDK API 3. API Classes

3 API Classes
The API consists of:
Main Classes
 AudioCodesUA – Audio Codes User Agent (Singleton) – see Section 3.1
 AudioCodesSession – for call representation (Interface) – see Section 3.2
 WebRTCAudioManager – class for managing audio routes – see Section 3.3
Helper Classes
 ACConfiguration – (Optional) class for general configuration options – see Section 3.4
 VideoConfiguration – (Optional) class for video configuration – see Section 3.5
 DTMFOptions – Class for settings DTMF options – see Section 3.6
 RemoteContact – Class representing the remote contact – see Section 3.7
Listener Interfaces
 AudioCodesEventListener – event listener for incoming calls and login state changes
– see Section 4.1
 AudioCodesSessionEventListener – event listener for call related events – see
Section 4.2
 WebRTCAudioRouteListener – event listener for audio route events – see Section 4.3

SDK API 13 WebRTC

 API Reference Guide

3.1 AudioCodesUA
Used to initialize the framework before starting to make and receive calls. Mostly used to
initialize the Web RTC engine and register to the service.
Class AudioCodesUA{
AudioCodesUA getInstance();
void setServerConfig(String proxyAddress, int port, String
domain, Transport transport, List<PeerConnection.IceServer>
iceServerList);
void setAccount (String userName, String password, String
displayName);
void setAccount (String userName, String password, String
displayName, String authName);
void setListeners (AudioCodesEventListener listener);
void login(Context context);
void logout();
AudioCodesSession call(RemoteContact call_to , boolean
withVideo, Hashtable<String, String> inviteHeaders);
void setRegisterExtraHeaders(Hashtable<String, String>
headers);
void setInviteExtraHeaders(Hashtable<String, String> headers);
String getUserAgent();
void setUserAgent(String userAgent);
int getRegExpires();
void setRegExpires(int registerExpires);
void setUseSessionTimer(boolean use);
void setLogLevel(LogLevel level);
void setLogger(ILog log);
void handleNetworkChange();
ArrayList<AudioCodesSession> getSessionList();
Void setContactRewrite(boolean enable);
}

3.1.1 Standard Methods

3.1.1.1 getInstance
Returns the singleton object instance of class AudioCodesUA.

3.1.1.2 setServerConfig
Configures the server.

Parameters
 proxyAddress [String, address of server]
 port [int, port of the proxy server address
 serverDomain [String, domain name to register to]
 transport [Transport, transport for connection to the server – UDP/TCP/TLS]
 iceServerList [List<PeerConnection.IceServer> , List of STUN and TURN servers]

Return Values
N/A

WebRTC Android Client SDK API 14 Document #: LTRT-14062

WebRTC Android Client SDK API 3. API Classes

3.1.1.3 setAccount (1)

Defines the account details. For this method, the authorization name is the same as the
username.

Parameters
 userName [String, authenticating user name]
 password [String, authenticating user password]
 displayName [String, display name for the user]

Return Values
N/A

3.1.1.4 setAccount (2)

Defines the account details. This is the same as setAccount (1) but with the option of having
a different authorization name.

Parameters
 userName [String, user name]
 password [String, authenticating user password]
 displayName [String, display name for the user]
 authName [String, authorization user name]

Return Values
N/A

3.1.1.5 setListeners
Defines the listeners object.

Parameters
 listener [AudioCodesEventListener, instance implementation of the
AudioCodesEventListener interface that holds the methods to be triggered; see
Section 4.1 for details on how it is defined; see also Section 5.2 for an
example]._API_Callbacks/_Listeners_User_Agent:_Set

Return Values
N/A

SDK API 15 WebRTC

 API Reference Guide

3.1.1.6 login
Performs registration to the service.

Parameters
 context [Context, Android application context]

Return Values
N/A

3.1.1.7 logout
Performs de-registration from the service.

Parameters
N/A

Return Values
N/A

3.1.1.8 call
Initiates an outgoing call.

Parameters
 call_to [RemoteContact, destination address/number]
 withVideo [boolean, 'True' if the call is initiated with video]
 inviteHeaders [Hashtable<String, String>, list of headers with a key/value where each
key is added as a header to the SIP INVITE with the specified value]

Return Values
 session [AudioCodesSession, a call session object defined here.]

WebRTC Android Client SDK API 16 Document #: LTRT-14062

WebRTC Android Client SDK API 3. API Classes

3.1.2 Advanced Methods

The advanced methods are optional. They provide an extra level of flexibility to the API,
which is based on SIP (Session Initiation Protocol). Developers who are familiar with SIP
can make use of the advanced methods.

3.1.2.1 setRegisterExtraHeaders
Allows adding additional headers to the registration request.

Note: The headers must be SIP headers that conform to RFC 3261.

Parameters
 headers [Hashtable<String, String>, list of headers with a key/value where each key is
added as a header to the registration request with the specified value]

Return Values
N/A

3.1.2.2 setInviteExtraHeaders
Allows adding additional headers to the INVITE request or response.

Note: The headers must be SIP headers that conform to RFC 3261.

Parameters
 headers [Hashtable<String, String>, list of headers with a key/value where each key is
added as a header to the SIP INVITE with the specified value]

Return Values
N/A

3.1.2.3 getUserAgent
Gets the current user-agent string, used to build the SIP header User-Agent.

Parameters
N/A

Return Values
 User agent [String, text describing the SIP user agent]

SDK API 17 WebRTC

 API Reference Guide

3.1.2.4 setUserAgent
Sets the user-agent string, used to build the SIP header User-Agent.

Parameters
 User agent [String, text describing the SIP User Agent]

Return Values
N/A

3.1.2.5 getRegExpires
Gets the current default registration interval.

Parameters
N/A

Return Values
 expires [integer, seconds]

3.1.2.6 setRegExpires
Changes the default registration interval from the default value (600).

Parameters
 expires [integer, seconds]

Return Values
N/A

3.1.2.7 setUseSessionTimer
Allows enabling session timers in the call session.

Parameters
 use [boolean, if false then the session timers will be not be enabled, otherwise (default
value) session timers will be optionally supported. E.g., the SBC will initiate session
timers if configured to do so]

Return Values
N/A

WebRTC Android Client SDK API 18 Document #: LTRT-14062

WebRTC Android Client SDK API 3. API Classes

3.1.2.8 setLogLevel
Changes the log level used by the application. Release builds might want to set the log level
higher for security reasons. WebRTC internal logs are only enabled if the debug level is lower
than or equal to DEBUG level.

Parameters
 logLevel [LogLevel, log level enum]

Return Values
N/A

3.1.2.9 setLogger
Changes the logger used by the SDK. Logs for the WebRTC SDK and logs for PjSIP are
written to the custom logger. WebRTC internal logs are still be written to the console (if the
log level is lower than debug)

Parameters
 logger [ILog, instance object of the ILog interface]

Return Values
N/A

3.1.2.10 handleNetworkChange
Handles network changes when called. This re-registers the client and reestablishes the
audio sessions when the network has been changed.
Must be explicitly called by the client application. The SDK does not automatically detect a
network change. Ideally, this must be called when the network is reconnected, not when
disconnected.

Parameters
N/A

Return Values
N/A

SDK API 19 WebRTC

 API Reference Guide

3.1.2.11 getSessionList
Gets the current session list.

Parameters
N/A

Return Values
List of sessions [ArrayList<AudiocodesSession>, list of active sessions]

3.1.2.12 setContactRewrite
This option is used to update the transport address and the Contact header of REGISTER
request. When this option is enabled, the SDK keeps track of the public IP address from the
response of the REGISTER request. Once it detects that the transport address has changed,
it will unregister the current Contact, update the Contact with the transport address learned
from the Via header, and register a new Contact to the registrar. It will also update the public
name of the UDP transport if STUN (Session Traversal Utilities for NAT) is configured.

Default: false

Parameters
 enable [Boolean]–
true - the library tracks the public IP address from the response of the REGISTER
request.
false - the library does not track the public IP address from the response of the
REGISTER request.

Return Values
N/A

WebRTC Android Client SDK API 20 Document #: LTRT-14062

WebRTC Android Client SDK API 3. API Classes

3.2 AudioCodesSession
Represents a call session. Used in two scenarios:
 When initiating a call via the AudioCodesUA
 When receiving a callback of an incoming call

Syntax
class AudioCodesSession {
int getSessionID();
void answer(Hashtable<String, String> inviteHeaders, boolean
withVideo) ;
void reject(Hashtable<String, String> inviteHeaders);
void terminate();
void muteAudio(boolean mute);
void muteVideo(boolean mute);
boolean isAudioMuted();
boolean isVideoMuted();
void sendDTMF(DTMF dtmf);
boolean isOutgoing();
boolean hasVideo();
RemoteContact getRemoteNumber();
CallState getCallState();
int duration();
long getCallStartTime();
CallTermination getTermination();
boolean isLocalHold();
boolean isRemoteHold();
Object getUserData();
void setUSerData(Object object);
vold hold(boolean hold);
void switchCamera();
void showVideo(Activity);
void showVideo(SurfaceViewRenderer localView,
SurfaceViewRenderer remoteView);
void stopVideo();
void setLocaLRenderPosition(int xPercentage, int yPercentage);
void addSessionEvenListener(AudioCodesSessionEventListener
sessionEventListener);
void removeSessionEvenListener(AudioCodesSessionEventListener
sessionEventListener);
ACCallStatistics getStats();
void redirect(RemoteContact contact, Hashtable<String,String>
inviteHeaders);
void reinviteWithVideo();
}

SDK API 21 WebRTC

 API Reference Guide

3.2.1 Standard Methods

3.2.1.1 getSessionID
Retrieves the internal identifier for the session. This identifier can be used in case there is
more than one session.

Parameters
N/A

Return Values
 sessionID [int, ID of the session]

3.2.1.2 answer
Initiates the object and establishes the call. Only valid for incoming calls.

Parameters
 headers [Hashtable<String, String>, list of headers with a key/value where each key is
added as a header to the SIP response with the specified value]
 withvideo [boolean, True - the call will be answered with video and video unmuted.
Both sides will see each other.
False - the call will be answered with video, but video muted. This side will see the
remote video, but the remote side cannot see the local side video].

Return Values
N/A

3.2.1.3 reject
Rejects a call. Only valid for incoming calls.

Parameters
 headers [Hashtable<String, String>, list of headers with a key/value where each key is
added as a header to the SIP response with the specified value]

Return Values
N/A

3.2.1.4 Terminate
Terminates an active call. Only valid for outgoing and established calls.

Parameters
N/A

Return Values
N/A

WebRTC Android Client SDK API 22 Document #: LTRT-14062

WebRTC Android Client SDK API 3. API Classes

3.2.1.5 muteAudio
Defines the status of the audio mute (on/off).

Parameters
 Mute [boolean, value. 'True' to mute audio; 'False' to unmute audio]

Return Values
N/A

3.2.1.6 muteVideo
Defines the status of the video mute (on/off).

Parameters
 mute [boolean, value; 'True' to mute video; 'False' to unmute video]

Return Values
N/A

3.2.1.7 isAudioMute
Checks audio mute status.

Parameters
N/A

Return Values
 mute [boolean, 'True' if mute, 'False' if not]

3.2.1.8 isVideoMute
Checks video mute status.

Parameters
N/A

Return Values
 mute [boolean, 'True' if mute, 'False' if not]

SDK API 23 WebRTC

 API Reference Guide

3.2.1.9 sendDTMF
Sends a DTMF character

Parameters
 dtmf [DTMF, an enum containing a DTMF character]

Return Values
N/A

3.2.1.10 isOutgoing
Checks if a call is outgoing.

Parameters
N/A

Return Values
 [boolean, 'True' if outgoing, 'False' if incoming.]

3.2.1.11 hasVideo
Checks if a call has video.

Parameters
N/A

Return Values
 [boolean, 'True' if the call has video, 'False' if the call is audio only].

3.2.1.12 getCallState
Gets the call state of the session.

Parameters
N/A

Return Values
 callstate [CallState, enum containing the call state]

WebRTC Android Client SDK API 24 Document #: LTRT-14062

WebRTC Android Client SDK API 3. API Classes

3.2.1.13 getTermination
Gets the termination reason of the session.

Parameters
N/A

Return Values
 termination [CallTermination, enum containing the termination reason]

3.2.1.14 duration
Defines the call duration, in seconds. It will be -1 if the call has still not been established.

Parameters
N/A

Return Values
 duration [int, call duration in seconds, -1 if the call is not yet established]

3.2.1.15 isLocalHold

Parameters
N/A

Return Values
 [boolean 'True' if call is on local hold, 'False' if otherwise]

3.2.1.16 isRemoteHold

Parameters
N/A

Return Values
 [boolean 'True' if the call is on local hold, 'False' if otherwise]

SDK API 25 WebRTC

 API Reference Guide

3.2.1.17 setUserData
Allows the optional setting of a user-created object / data to be attached to a certain session.
The reference is removed from the session after the session is terminated.

Parameters
 userData [Object, Java object for option user data]

Return Values
N/A

3.2.1.18 getUserData
Allows the optional retrieval of a user-created object / data which was attached to a certain
session.

Parameters
N/A

Return Values
 userData [Object, Java object for option user data]

3.2.1.19 hold
Set call on hold (or un-hold). The callProgress callback in.AudioCodesSessionEventListener
indicates when the call has been placed on hold/unhold.

Parameters
 Hold [Boolean, set call to hold]

Return Values
N/A

3.2.1.20 switchCamera
Switches the camera between front and back camera. This method requires the device to
have two cameras. A successful camera switch is returned in the cameraSwitched callback
in AudioCodesSessionEventListener.

Parameters
N/A

Return Values
N/A

WebRTC Android Client SDK API 26 Document #: LTRT-14062

WebRTC Android Client SDK API 3. API Classes

3.2.1.21 showVideo (1)

Displays video during a call. This requires the UI element ac_webrtc_video to be included in
the layout of the activity. This is the recommended method to be used when using video.
For a more advanced and customized option, see showVideo(2) in the section below.

Parameters
 Activity [Activity, Android activity that is used to display the video. This activity must
contain the ac_webrtc_video UI element in its content view.

Return Values
N/A

3.2.1.22 showVideo (2)

Displays video during a call. This does not require the UI element ac_webrtc_video to be
included in the layout of the activity. The method is mutually exclusive to showVideo (1).

Parameters
 localView [SurfaceViewRender, Android SurfaceViewRenderer UI element; this
element is used to show the local stream.
 remoteView [SurfaceViewRender, Android SurfaceViewRenderer UI element; this
element is used to show the remote stream.

Return Values
N/A

3.2.1.23 stopVideo
Stops the capturing of video and removes the remote and local renderer. In order to start
video again, showVideo needs to be called.

Parameters
N/A

Return Values
N/A

SDK API 27 WebRTC

 API Reference Guide

3.2.1.24 setLocalRenderPosition
Sets the local render position. Only relevant if showVideo(1) method is used.
This method should be called before showVideo.

Parameters
 xPercentage [int, the horizontal position of the top left side of the local render view.
This is set as a percentage of the ac_webrtc_video screen. E.g., if the local render
view has a width of 1000 pixels. Setting this item to 66 will place the the top left side of
the local render view at pixel 660 of the x-axis]
 yPercentage [int, the vertical position of the top left side of the local render view. This
is set as a percentage of the ac_webrtc_video screen. E.g., if the local render view
has a height of 1500 pixels. Setting this item to 66 will place the top left side of the
local render view at pixel 1000 of the y-axis]

Return Values
N/A

3.2.1.25 addSessionEventListener
Adds an event listener to listen for session events. The client application might add multiple
listeners. The listeners will receive events until they are other removed or the session was
terminated.

Parameters
 sessionEventListener[AudioCodesSessionEventListener, implementation object of the
AudioCodesSessiobEventListener interface]

Return Values
N/A

3.2.1.26 removeSessionEventListener
Removes a sessionEventListener that was previously added in the addSessionEventListener
method.

Parameters
 sessionEventListener[AudioCodesSessionEventListener, implementation object of the
AudioCodesSessiobEventListener interface]

Return Values
N/A

WebRTC Android Client SDK API 28 Document #: LTRT-14062

WebRTC Android Client SDK API 3. API Classes

3.2.1.27 getStats
Retrieves statistics on the entire call session.

Parameters
N/A

Return Values
 ACCallStatistics[ACCallStatistics, object containing the call statistics]

3.2.1.28 redirect
Redirects an incoming call to a new number. Indicates to the calling party that the caller
should try to call the number specified in RemoteContact (see also under here).

Parameters
 contact [RemoteContact, redirect destination address/number]
 inviteHeaders [Hashtable<String, String>, list of headers with a key/value where each
key is added as a header to the SIP INVITE with the specified value]

Return Values
 session [AudioCodesSession, a call session object defined here]

3.2.1.29 reinviteWithVideo
Enables video during a call. Sends a REINVITE with video enabled. Note that showVideo
will need to be called (see code example delivered with the SDK).

Parameters
N/A

Return Values
N/A

SDK API 29 WebRTC

 API Reference Guide

3.3 WebRTCAudioManager
WebRTC SDK Audio management. This class handles audio routing during WebRTC calls.

Syntax
class AudioCodesSession {
WebRTCAudioManager getInstance();
void setWebRTCAudioRouteListener(WebRTCAudioRouteListener
listener) ;
void setAudioRoute(AudioRoute route);
AudioRoute getAudioRoute();
List<AudioRoute> getAvailableAudioRoutes();
}

3.3.1 Standard Methods

3.3.1.1 getInstance
Gets the singleton instance of the WebRTCAudioManager class.

Parameters
N/A

Return Values
 instance [WebRTCAudioManager, singleton object instance]

3.3.1.2 setWebRTCAudioRouteListener
Sets a listener for listening to updates in the current audio route and available audio routes.
There must always be only one listener; setting a new listener will overwrite the previous
listener.

Parameters
 listener [WebRTCAudioRouteListener, implementation instance of the
WebRTCAudioRouteListener interface]

Return Values
N/A

WebRTC Android Client SDK API 30 Document #: LTRT-14062

WebRTC Android Client SDK API 3. API Classes

3.3.1.3 setAudioRoute
Sets the audio route. This method changes the audio route of the device. This generally
should be used during a call. The audio will be only be routed if the new audio route is
available.

Parameters
 audioRoute [AudioRoute, enum describing the new audio route]

Return Values
 [Boolean, true – if the new audio route was found
false – if the new audio route is not available ]

3.3.1.4 getAudioRoute
Gets the current audio route.

Parameters
N/A

Return Values
 audioRoute [AudioRoute, enum describing the new audio route]

3.3.1.5 getAvailableAudioRoutes
Gets the available audio routes.

Parameters
N/A

Return Values
 audioRouteList [List<AudioRoute>, list of enums with the available audio routes]

SDK API 31 WebRTC

 API Reference Guide

3.4 ACConfiguration
Used to provide additional configuration options for the WebRTC SDK. Using this class is
optional. The class is a singleton object. The configuration object can be retrieved through
getConfiguration. Any changes in that object will be applied to the SDK. It is recommended
to apply any changes before calling the AudioCodesUA login method.
Class ACConfiguration{
ACConfiguration getConfiguration();
String version();
int getLocalServerPort();
void setLocalServerPort(int port);
DTMFOptions getDTMFOptions();
void setDTMFOptions(DTMFOptions dtmfOptions);
VideoConfiguration getVideoConfiguration();
void setVideoConfiguration(VideoConfiguration configuration);
void setAutomaticCallOnRedirect(boolean automaticRedirect);
boolean getAutomaticCallOnRedirect();
void setRedirect(boolean redirect, RemoteContact
redirectContact);
RemoteContact getRedirectContact();
boolean getRedirectEnabled();
}

WebRTC Android Client SDK API 32 Document #: LTRT-14062

WebRTC Android Client SDK API 3. API Classes

3.4.1 Standard Methods

3.4.1.1 getConfiguration
Static method that returns the current used configuration object.

Parameters
N/A

Return Values
 configuration [ACConfiguration, current used configuration object; see Section 3.4]

3.4.1.2 version
Static method that returns the current version of the SDK.

Parameters
N/A

Return Values
 Version [String, version of the SDK, e.g., 1.x]

3.4.1.3 getLocalServerPort
Gets the current default local port used by the SIP stack.

Parameters
N/A

Return Values
 port [integer, default local user port (default 6000)]

3.4.1.4 setLocalServerPort
Changes the default local SIP server port from the default value (6000).

Parameters
 port [integer, default local server port]

Return Values
N/A

SDK API 33 WebRTC

 API Reference Guide

3.4.1.5 getDtmfOptions
Gets the current default local port used by the SIP stack

Parameters
N/A

Return Values
 dtmfOptions [DTMFOptions, DTMFOptions class for setting the handling of DTMF
tones; the default value is for the WebRTC to handle DTMF tones]

3.4.1.6 setDtmfOptions
Changes the DTMFOptions class used by the SDK. This allows for sending DTMF through
either the WebRTC or SIP INFO. The class allows for changing DTMF duration and interval
(if applicable for the chosen method). See Section 3.6 for more information.

Parameters
 dtmfOptions [DTMFOptions, DTMFOptions class for setting the handling of DTMF
tones]

Return Values
N/A

3.4.1.7 getVideoConfiguration
Gets the current video configuration used by the SDK.

Parameters
N/A

Return Values
 configuration [VideoConfiguration, class containing video configuration options]

3.4.1.8 setVideoConfiguration
Changes the video configurations options used by the SDK. See also Section 3.5.

Parameters
 configuration [VideoConfiguration, class containing video configuration options]

Return Values
N/A

WebRTC Android Client SDK API 34 Document #: LTRT-14062

WebRTC Android Client SDK API 3. API Classes

3.4.1.9 setAutomaticCallOnRedirect
Sets automatic call redirection for outgoing call redirection. If enabled, the SDK will
automatically attempt to call the number supplied in the 3XX response on the INVITE.
If not, the call will be terminated and the redirect number will be provided in the
callProgress (redirect) callback. See the code example delivered with the SDK. In this
case, the application using the SDK will be responsible for placing a new call to the new
number, if necessary.

Parameters
 automatic redirect [boolean, if True, automatic redirect will be enabled; otherwise
redirect will be disabled]

Return Values
N/A

3.4.1.10 getAutomaticCallOnRedirect
Gets the current setting for automatic call redirection.

Parameters
N/A

Return Values
 automatic redirect [boolean, if True, automatic redirect will be enabled; otherwise
redirect will be disabled]

3.4.1.11 setRedirect
This method allows for the setting of incoming call redirection. If enabled, all incoming calls
will be answered with a 302 response and the redirect contact provided in the
redirectContact field. If the redirect field is enabled, there will be no incoming call callbacks

Parameters
 redirect [boolean, if True, all incoming call redirection is enabled; if not, then redirect is
disabled]
 redirectContact [RemoteContact, the contact to whom the call should be redirected.
Only username is mandatory. The domain and scheme fields will be taken from the
user account if not provided.

Return Values
N/A

SDK API 35 WebRTC

 API Reference Guide

3.4.1.12 getRedirectContact
Gets the current contact that was set for incoming call redirection

Parameters
N/A

Return Values
 redirect contact [RemoteContact, current contact set for incoming call redirection]

3.4.1.13 getRedirectEnabled
Gets the current setting for incoming call redirection.

Parameters
N/A

Return Values
 incoming call redirect [boolean, if True, then incoming call redirection is enabled; if not,
then incoming call redirect is disabled]

WebRTC Android Client SDK API 36 Document #: LTRT-14062

WebRTC Android Client SDK API 3. API Classes

3.5 Video Configuration

Used to provide additional configuration options for the WebRTC SDK. Using this class is
optional. The class provides access to public parameters that can be changed if needed.
The configuration object can be retrieved through getVideoConfiguration in ACConfiguration
class. Calling setVideoConfiguration in the ACConfiguration class will apply the changes. It
is recommend to call setVideoConfiguration before showVideo is called.

Class VideoConfiguration{
}

3.5.1 Camera Parameters

 cameraWidth – captures the width of the camera (default 640)
 cameraHeight - captures the height of the camera (default 480)
 cameraFrameRate - captures the framerate of the camera (default 15)

3.5.2 Rendering Views Parameters

 LOCAL_X_CONNECTING – Uppermost left corner (% of the screen width) of the
local video screen when a remote video stream is not yet available.
 LOCAL_Y_CONNECTING - Uppermost left corner (% of the screen height) of the
local video screen when a remote video stream is not yet available.
 LOCAL_WIDTH_CONNECTING – Lowermost right corner (% of the screen width) of
the local video screen when a remote video stream is not yet available.
 LOCAL_HEIGHT_CONNECTING – Lowermost right corner (% of the screen height)
of the local video screen when a remote video stream is not yet available.

 LOCAL_X_CONNECTED - Uppermost left corner (% of the screen width) of the local

video screen when a remote video stream is available.
 LOCAL_Y_CONNECTED - Uppermost left corner (% of the screen height) of the local
video screen when a remote video stream is available.
 LOCAL_WIDTH_CONNECTED – Lowermost right corner (% of the screen width) of
the local video screen when a remote video stream is available.
 LOCAL_HEIGHT_CONNECTED – Lowermost right corner (% of the screen height) of
the local video screen when a remote video stream is available.

 REMOTE_X - Uppermost left corner (% of the screen width) of the remote video
screen when a remote video stream is available.
 REMOTE_Y - Uppermost left corner (% of the screen height) of the remote video
screen when a remote video stream is available.
 REMOTE_WIDTH - Lowermost right corner (% of the screen width) of the remote
video screen when a remote video stream is available
 REMOTE_HEIGHT - Lowermost right corner (% of the screen height) of the remote
video screen when a remote video stream is available

SDK API 37 WebRTC

 API Reference Guide

3.6 DTMF Options

Used to provide additional configuration options for the WebRTC SDK. Using this class is
optional. The class provides access to public parameters that can be changed if needed.
The class allows configuration of sending DTMF events.

Class DTMFOptions{
}

3.6.1 DTMF Parameters

 dtmfMethod - DTMFMethod enum parameter that supports sending of DTMF
through:
• WEBRTC - DTMF is sent through media by telephone-event using the WebRTC
engine. This is the default method.
• SIP_INFO - DTMF events are sent through SIP_INFO events.
 duration - duration of the DTMF event, in milliseconds. When using SIP_INFO, the
minimum is 100, which is the default value.
 intervalGap - the interval gap in milliseconds between sending DTMF events. This is
only relevant for WEBRTC DTMF events. Default: 70.

WebRTC Android Client SDK API 38 Document #: LTRT-14062

WebRTC Android Client SDK API 3. API Classes

3.7 Remote Contact

Used to represent a remote contact. This can be either a dialed number or a remote
contact received through an incoming call.

Class RemoteContact{
String getDisplayName();
String getUserName();
String getDomain();
void setDisplayName(String displayName);
void setUserName(String username);
void setDomain(String domain);

3.7.1 Standard Methods

3.7.1.1 getDisplayName
Gets the contact display name. Note that this might not be available since the remote
contact did not set a display name.

Parameters
N/A

Return Values
 displayName [String, display name of the remote contact]

3.7.1.2 getUserName
Gets the contact user name.

Parameters
N/A

Return Values
 userName [String, user name of the remote contact]

SDK API 39 WebRTC

 API Reference Guide

3.7.1.3 getDomain
Gets the contact domain.

Parameters
N/A

Return Values
 domain [String, domain of the remote contact]

3.7.1.4 setDisplayName
(Optional) Sets the contact display name. Since this does not affect SIP signaling, it's
optional; it allows for easier retrieval of the display name used in the call.

Parameters
 displayName [String, display name of the remote contact]

Return Values
N/A

3.7.1.5 setUsername
Sets the contact user name.

Parameters
 userName [String, user name of the remote contact]

Return Values
N/A

3.7.1.6 setDomain
(Optional) Sets the contact domain.

Parameters
 domain [String, domain of the remote contact. This value doesn't usually have to be
set as the remote contact is likely to reside in the same domain]

Return Values
N/A

WebRTC Android Client SDK API 40 Document #: LTRT-14062

WebRTC Android Client SDK API 4. API Callbacks/ Listeners Interfaces

4 API Callbacks/ Listeners Interfaces

The API provides capability to register in order to listen to different types of events. Here's a
list of the interfaces that must be implemented in order to receive an event:

4.1 AudioCodes Event Listener

Interface for receiving SDK events. This interface must be implemented and set through the
AudioCodesUA class to receive these event.

4.1.1 LoginStateChanged
Triggered when the login state has been changed.

Syntax
void loginStateChanged(boolean isLogin, String cause);

Parameters
 IsLogin [boolean, 'True' if logged in and 'False' if not logged in]
 cause [String, text describing the received SIP reason. This can be mostly used if
more information on a login failure is required]

4.1.2 incomingCall
Triggered when receiving an incoming call.

Syntax
void incomingCall(AudioCodesSession call);

Parameters
 Session [AudioCodesSession, the incoming call session object]

SDK API 41 WebRTC

 API Reference Guide

4.2 AudioCodes Session Event Listener

4.2.1 callTerminated
Callback for when the session is terminated by the local or the remote side.

Syntax
void callTerminated(AudioCodesSession session);

Parameters
 session [AudioCodesSession, the call session object that was terminated. The object
will be removed at the of the callTerminated method]

4.2.2 callProgress
Callback for changes in the state of the call. The call progress state can be retrieved by
getCallState in the AudioCodesSession object.

Syntax
void callProgress(AudioCodesSession call);

Parameters
 session [AudioCodesSession, the call session object]

4.2.3 cameraSwitched
Callback for when the camera has been switched between the front or the back camera.

Syntax
void cameraSwitched(boolean frontCamera);

Parameters
 frontCamera [boolean, True – the camera has switched to the front camera;
False – the camera has switched to the back camera]

WebRTC Android Client SDK API 42 Document #: LTRT-14062

WebRTC Android Client SDK API 4. API Callbacks/ Listeners Interfaces

4.2.4 reinviteWithvideoCallback

Callback for when video is added during a call. This callback can be used to call
showVideo (from the UI thread). See the code example delivered with the SDK.

Syntax
void reinviteWithVideoCallback(AudiocodesSession session);

Parameters
 session [AudioCodesSession, the call session object]

4.3 Web RTC Audio Route Listener

Interface for receiving audio routes events. The interface must be implemented and set
through the WebRTCAudioManager class to receive these events.

4.3.1 audioRoutesChanged
Callback for when the list of available audio routes has been changed, for example, if the
user is connected to a Bluetooth audio device

Syntax
void audioRoutesChanged(List<WebRTCAudioManager.AudioRoute>
audioRouteList);

Parameters
 audioRouteList [List<WebRTCAudioManager.AudioRoute>, a list of available audio
routes]

4.3.2 currentAudioRouteChanged
Callback for when the currently used audio route has been changed. E.g., if the user adds a
Bluetooth audio device, the SDK will route the audio to the Bluetooth device and this callback
will be called.

Syntax
void currentAudioRouteChanged(WebRTCAudioManager.AudioRoute
newAudioRoute);

Parameters
 newAudioRoute [WebRTCAudioManager.AudioRoute, the new audio route where the
audio is being routed to]

SDK API 43 WebRTC

 API Reference Guide

This page is intentionally left blank.

WebRTC Android Client SDK API 44 Document #: LTRT-14062

WebRTC Android Client SDK API 5. Use Examples

5 Use Examples
Here are some use examples for your reference.

5.1 User Agent: Create Instance, Set Server and Account

AudioCodesUA phone = new AudioCodesUA(); // phone API
ArrayList<PeerConnection.IceServer> iceServerList = new
ArrayList<PeerConnection.IceServer>();
phone.setServerConfig(“webrtclab.audiocodes.com”, 5080,
“example.com”,Transport.TCP, iceServerList);
phone.setAccount(“John”, “******”, “John Smit”, “jsmit”);

5.2 User Agent: Set Listeners (callbacks)

phone.setListener(new AudioCodesEventListener() {
@Override
public void loginStateChanged(boolean isLogin, String cause) {
// place your code here (remember that this is being called
//on the WebRTC SDK thread, not on the UI thread)
}

@Override
public void incomingCall(AudioCodesSession session) {
// place your code here (remember that this is being called
//on the WebRTC SDK thread, not on the UI thread)
}
});

5.3 User Agent login: Connection to SBC server, and

Login
phone.login(getApplicationContext()); // getApplicationContext is
an Android method available for Activities and Services

5.4 Make a Call

boolean withVideo = true;
AudioCodesSession activeCall = phone.call(“jane”, withVideo,
null);

5.5 Send DTMF during Call

activeCall.sendDTMF(DTMF.NINE);

5.6 Mute / Unmute During Call

activeCall.muteAudio(true);
activeCall.muteAudio(false);

5.7 Accept Incoming Call (with Video)

incomingCall.answer(null, true);

SDK API 45 WebRTC

 API Reference Guide

5.8 Reject Incoming Call

incomingCall.reject(null);

5.9 Terminate a Call

activeCall.terminate();

5.10 Use of Video

Include the ac_webrtc_video UI element in the XML file for your call activity:

<include
android:id="@+id/my_ac_webrtc_video"
layout="@layout/ac_webrtc_video"
android:layout_width="match_parent"
android:layout_height="match_parent" />
Update the position of your local render screen:
activeCall.setLocalRenderPosition(70,60);
Call showVideo with your call activity; the WebRTC SDK will locate the ac_webrtc_video UI
element and use it to display the remote and the local video:
activeCall.showVideo(CallActivity.this);

WebRTC Android Client SDK API 46 Document #: LTRT-14062

WebRTC Android Client SDK API 5. Use Examples

This page is intentionally left blank.

SDK API 47 WebRTC

International Headquarters
1 Hayarden Street,
Airport City
Lod 7019900, Israel
Tel: +972-3-976-4000
Fax: +972-3-976-4040

AudioCodes Inc.
27 World’s Fair Drive,
Somerset, NJ 08873
Tel: +1-732-469-0880
Fax: +1-732-469-2298

Contact us: https://www.audiocodes.com/corporate/offices-worldwide

Website: https://www.audiocodes.com/

©2018 AudioCodes Ltd. All rights reserved. AudioCodes, AC, HD VoIP, HD VoIP Sounds Better, IPmedia, Mediant,
MediaPack, What’s Inside Matters, OSN, SmartTAP, User Management Pack, VMAS, VoIPerfect, VoIPerfectHD, Your
Gateway To VoIP, 3GX, VocaNom, AudioCodes One Voice and CloudBond are trademarks or registered trademarks of
AudioCodes Limited. All other products or trademarks are property of their respective owners. Product specifications
are subject to change without notice.

Document #: LTRT-14062