Child classes

Call(callInstance, media)

A media call session for voice and/or video

Callee(regId)

The callee of a call

Caller(pin, regId, uri)

The caller of a call

CallMediaStatus()

The media status of a call

CallOptions(video, remoteRender, localRender)

Options applied to a call

CallStatus()

The status of the call when it is terminated

DataConnection(session, media)

A connection used to transmit data at real-time

Exceptions()

The various errors the Media class may throw.

Classes

Properties

static

CallEndCause  number

Call ending causes that is returned to the client

Properties

Name Type Optional Description

CALL_SUCCESS

 

 

Call completed without error

CALL_FAILURE_FIREWALL

 

 

Call failed due to media blocked by firewall or network congestion

CALL_FAILURE_MEDIASETUP

 

 

Call failed during setting up the media connections

CALL_FAILURE_NOMEDIA

 

 

Call failed due to media connection lost and couldn't be regained

CALL_END_USER

 

 

Call ended due to user operations

CALL_TIMEOUT

 

 

Call timed out

CALL_CANCELLED_UNKNOWN

 

 

Call canceled before connected

CALL_END_NETWORKUNAVAILABLE

 

 

Call disconnected as the network is unavailable

CALL_END_PEER

 

 

Call disconnected with other unknown reasons

CALL_RECOVERY_CALL_TRANSFER

 

 

Call terminated due to recovery call is made

CALL_SECURE_CALL_UNSUPPORTED

 

 

Call failed due to secure call negotiation error

CALL_SECURE_CALL_KEY_ERROR

 

 

Call failed due to secure call has mismatched keys

CALL_SECURE_CALL_KEY_TIMEOUT

 

 

Call failed due to secure call timed out in encryption/decryption operations

CALL_END_BUSY

 

 

Call rejected by the callee due to conflict

CALL_REJECTED_ELSEWHERE

 

 

Call rejected by another end point of the user

Typically, the client receiving this cause should silently drop the call without having to create a call history, as the other endpoint rejecting the call should have created a call history already.

CALL_ACCEPTED_ELSEWHERE

 

 

Call accepted by another end point of the user

Typically, the client receiving this cause should silently drop the call without having to create a call history, as the other endpoint accepting the call should create a call history once the call disconnects.

static

CallEndReason  number

Call ending reasons that is passed from the user to the media instance

Properties

Name Type Optional Description

USER_HANGUP

 

 

Normal hangup

REJECT_CALL

 

 

Rejected

TIMEOUT

 

 

No answer for a certain period of time after ringing

FAILURE_MEDIASETUP

 

 

Answer failed due to media unavailable

e.g. answering with video failed as camera is not available and the client decides to fail the call

static

CallQosLevels  number

The Call Quality Status codes that is returned to the client Upon SparkCommunications.Media.Call#event:qualityChanged

Properties

Name Type Optional Description

QUALITY_UNKNOWN

 

 

quality is unknown as not enough samples have been collected

QUALITY_GOOD

 

 

quality is good and no visual or audible glitches should appear

QUALITY_MODERATE

 

 

quality is moderate and minor visual or audible glitches may appear

QUALITY_POOR

 

 

quality is poor and major visual or audible glitches may appear

static

CallState  number

The state of the call session

Properties

Name Type Optional Description

CALL_STATE_UNKNOWN

 

 

Unknown state

CALL_STATE_INITIATED

 

 

Call has been created/initiated

CALL_STATE_RINGING

 

 

Call is ringing on both ends

CALL_STATE_CONNECTING

 

 

Call has been accepted by the callee and is waiting for the caller to ACK

CALL_STATE_CONNECTED

 

 

Call has been established successfully

CALL_STATE_DISCONNECTED

 

 

Call has been disconnected

static

Features  number

Features supported by the Media class

Properties

Name Type Optional Description

MEDIA_CALL

 

 

Voice and Video Call

DATA_CONNECTION

 

 

Data Connection

static

SipStatusCode  number

The SIP Status codes that is returned to the client.

See RFC3261 for full description

Properties

Name Type Optional Description

TRYING

 

 

RINGING

 

 

CALL_BEING_FORWARDED

 

 

QUEUED

 

 

PROGRESS

 

 

OK

 

 

ACCEPTED

 

 

MULTIPLE_CHOICES

 

 

MOVED_PERMANENTLY

 

 

MOVED_TEMPORARILY

 

 

USE_PROXY

 

 

ALTERNATIVE_SERVICE

 

 

BAD_REQUEST

 

 

UNAUTHORIZED

 

 

PAYMENT_REQUIRED

 

 

FORBIDDEN

 

 

NOT_FOUND

 

 

METHOD_NOT_ALLOWED

 

 

NOT_ACCEPTABLE

 

 

PROXY_AUTHENTICATION_REQUIRED

 

 

REQUEST_TIMEOUT

 

 

GONE

 

 

REQUEST_ENTITY_TOO_LARGE

 

 

REQUEST_URI_TOO_LONG

 

 

UNSUPPORTED_MEDIA_TYPE

 

 

UNSUPPORTED_URI_SCHEME

 

 

BAD_EXTENSION

 

 

EXTENSION_REQUIRED

 

 

SESSION_TIMER_TOO_SMALL

 

 

INTERVAL_TOO_BRIEF

 

 

TEMPORARILY_UNAVAILABLE

 

 

CALL_TSX_DOES_NOT_EXIST

 

 

LOOP_DETECTED

 

 

TOO_MANY_HOPS

 

 

ADDRESS_INCOMPLETE

 

 

PJSIP_AC_AMBIGUOUS

 

 

BUSY_HERE

 

 

REQUEST_TERMINATED

 

 

NOT_ACCEPTABLE_HERE

 

 

BAD_EVENT

 

 

REQUEST_UPDATED

 

 

REQUEST_PENDING

 

 

UNDECIPHERABLE

 

 

INTERNAL_SERVER_ERROR

 

 

NOT_IMPLEMENTED

 

 

BAD_GATEWAY

 

 

SERVICE_UNAVAILABLE

 

 

SERVER_TIMEOUT

 

 

VERSION_NOT_SUPPORTED

 

 

MESSAGE_TOO_LARGE

 

 

PRECONDITION_FAILURE

 

 

BUSY_EVERYWHERE

 

 

DECLINE

 

 

DOES_NOT_EXIST_ANYWHERE

 

 

NOT_ACCEPTABLE_ANYWHERE

 

 

Methods

static

featureSupported(features) → (Boolean or Array)

Checks if certain features can be supported on the platform.

Parameter

Name Type Optional Description

features

(Enum or Array)

 

features Either an enum of SparkCommunications.Media.Features, or an array containing multiple of the enums.

Returns

(Boolean or Array) 

true if the specific feature can be supported on the platform, or an array of the results if an array is given for features.

static

supported() → Boolean

Checks whether WebRTC can be supported on the platform.

Returns

Boolean 

true if WebRTC can be supported on the platform.

createDataConnection(callee, metaData, packetSize) → Promise

Makes an outgoing request to establish a data connection.

Parameters

Name Type Optional Description

callee

Object

 

the callee SparkCommunications.Media.Callee of the outgoing request.

metaData

Object

 

an object sent to the callee as meta data of the request.

It is typically used to describe the purpose of the data connection.

packetSize

Number

 

override the default size of each packet sent over the network.

  • Do not set this value if you would like to maintain compatibility among browsers.
  • Inappropriate setting may degrade the performance.
Throws

SparkCommunications.Media.Exceptions.NotSupportedError 

if the media features are not supported on the platform.

SparkCommunications.Media.Exceptions.InvalidArgumentError 

if the arguments are invalid.

SparkCommunications.Media.Exceptions.InvalidStateError 

if the call cannot be made due to transport state (e.g. no connection).

Returns

Promise 

a Promise, which is resolved to a DataConnection object SparkCommunications.Media.DataConnection and may reject to the following errors:

  1. SparkCommunications.Media.Exceptions.TimeoutError if the data connection fails to be requested due to timeout. e.g. if the server failed to resolve the callee's identity.

  2. SparkCommunications.Media.Exceptions.InvalidStateError if the data connection fails to be requested due to connection state. e.g. if the connection to server has dropped during the request.

hasAudioDevice() → Promise

Checks whether there is audio device that could capture the microphone locally.

Returns

Promise 

a promise that resolves to true if there is audio device found, otherwise it is resolved to false.

It may reject with the following errors:

  1. SparkCommunications.Media.Exceptions.NotSupportedError if the platform does not support querying the media devices.

hasVideoDevice() → Promise

Checks whether there is video device that could capture video locally.

Returns

Promise 

a promise that resolves to true if there is video device found, otherwise it is resolved to false.

It may reject with the following errors:

  1. SparkCommunications.Media.Exceptions.NotSupportedError if the platform does not support querying the media devices.

makeCall(callee, callOptions) → Promise

Makes an outgoing voice/video call.

Parameters

Name Type Optional Description

callee

Object

 

the callee SparkCommunications.Media.Callee of the outgoing call.

callOptions

Object

 

the call options SparkCommunications.Media.CallOptions of the outgoing call.

Throws

SparkCommunications.Media.Exceptions.NotSupportedError 

if the media calls are not supported on the platform.

SparkCommunications.Media.Exceptions.InvalidArgumentError 

if the arguments are invalid.

SparkCommunications.Media.Exceptions.InvalidStateError 

if the call cannot be made due to transport state (e.g. no connection).

Returns

Promise 

a Promise, which is resolved to a call object SparkCommunications.Media.Call and may reject to the following errors:

  1. SparkCommunications.Media.Exceptions.NotSupportedError if the requested call options cannot be satisfied, e.g. video device is unavailable on the platform when the video option is enabled.

  2. SparkCommunications.Media.Exceptions.PermissionDeniedError if the media fails to be requested due to permission error. e.g. if the user denied the request to allow camera or mic to be accessed.

  3. SparkCommunications.Media.Exceptions.TimeoutError if the media fails to be requested due to timeout. e.g. if the server failed to resolve the callee's identity.

  4. SparkCommunications.Media.Exceptions.InvalidStateError if the media fails to be requested due to connection state. e.g. if the connection to server has dropped during the request.

Events

incomingCall

An incoming media call is received

Parameter

Name Type Optional Description

The

Object

 

call session SparkCommunications.Media.Call representing the incoming call

incomingDataConnection

An incoming Data Connection is received

Parameter

Name Type Optional Description

The

Object

 

data connection SparkCommunications.Media.DataConnection that is created