Call (Voice Android 5.0.2)

java.lang.Object
- InternalCall
- - com.twilio.voice.Call

public class Call
extends InternalCall

The Call class represents a signaling and media session between the host device and Twilio infrastructure. Calls can represent an outbound call initiated from the SDK via Voice.connect(...) or an incoming call accepted via a CallInvite. Devices that initiate an outbound call represent the caller and devices that receive a CallInvite represent the callee.

The lifecycle of a call differs for the caller and the callee. Making or accepting a call requires a Call.Listener which provides Call state changes defined in Call.State. The Call.State can be obtained at any time by calling getState().

A subset of Android devices provide an OpenSLES implementation. Although more efficient, the use of OpenSLES occasionally results in echo. As a result, the Voice SDK disables OpenSLES by default for both incoming and outgoing Calls unless explicitly enabled. To enable OpenSLES execute the following before invoking Voice#connect(Context, ConnectOptions, Listener) or CallInvite#accept(Context, Listener):

tvo.webrtc.voiceengine.WebRtcAudioManager.setBlacklistDeviceForOpenSLESUsage(false)

The following table provides expected call sequences for common scenarios from the caller perspective. The caller scenario sequences are affected by the answerOnBridge flag provided in the Dial verb of your TwiML application associated with the client. If the answerOnBridge flag is false, which is the default, the Call.Listener.onConnected(Call) callback will be emitted immediately after Call.Listener.onRinging(Call). If the answerOnBridge flag is true this will cause the call to emit the Call.Listener.onConnected(Call) callback only until the call is answered by the callee. See the Answer on Bridge documentation for more details on how to use it with the Dial TwiML verb.

Caller Scenario	`Call.Listener` callbacks	`Call.State` transitions
A `Call` is initiated and the caller disconnects before reaching the `Call.State.RINGING` state.	`Call.Listener.onDisconnected(Call, CallException)`	`Call.State.CONNECTING` `Call.State.DISCONNECTED`
A `Call` is initiated, reaches the `Call.State.RINGING` state, and the caller disconnects before being `Call.State.CONNECTED`.	`Call.Listener.onRinging(Call)` `Call.Listener.onDisconnected(Call, CallException)`	`Call.State.CONNECTING` `Call.State.RINGING` `Call.State.DISCONNECTED`
A `Call` is initiated and the `Call` fails to connect before reaching the `Call.State.RINGING` state.	`Call.Listener.onConnectFailure(Call, CallException)`	`Call.State.CONNECTING` `Call.State.DISCONNECTED`
A `Call` is initiated and the `Call` fails to connect after reaching the `Call.State.RINGING` state.	`Call.Listener.onRinging(Call)` `Call.Listener.onConnectFailure(Call, CallException)`	`Call.State.CONNECTING` `Call.State.RINGING` `Call.State.DISCONNECTED`
A `Call` is initiated, becomes `Call.State.CONNECTED`, and ends for one of the following reasons: The caller disconnects the `Call` The callee disconnects the `Call` An on-device error occurs. (eg. network loss) An error between the caller and callee occurs. (eg. media connection lost or Twilio infrastructure failure)	`Call.Listener.onRinging(Call)` `Call.Listener.onConnected(Call)` `Call.Listener.onDisconnected(Call, CallException)`	`Call.State.CONNECTING` `Call.State.RINGING` `Call.State.CONNECTED` `Call.State.DISCONNECTED`

The following table provides expected call sequences for common scenarios from the callee perspective:

Callee Scenario	`Call.Listener` callbacks	`Call.State` transitions
A `CallInvite` is accepted and the callee disconnects the `Call` before being `Call.State.CONNECTED`.	`Call.Listener.onDisconnected(Call, CallException)`	`Call.State.CONNECTING` `Call.State.DISCONNECTED`
A `CallInvite` is accepted and the `Call` fails to reach the `Call.State.CONNECTED` state.	`Call.Listener.onConnectFailure(Call, CallException)`	`Call.State.CONNECTING` `Call.State.DISCONNECTED`
A `CallInvite` is accepted, becomes `Call.State.CONNECTED`, and ends for one of the following reasons: The caller disconnects the `Call` The callee disconnects the `Call` An on-device error occurs. (eg. network loss) An error between the caller and callee occurs. (eg. media connection lost or Twilio infrastructure failure)	`Call.Listener.onConnected(Call)` `Call.Listener.onDisconnected(Call, CallException)`	`Call.State.CONNECTING` `Call.State.CONNECTED` `Call.State.DISCONNECTED`
A `CallInvite` is rejected.	Reject will not result in any callbacks.	The call invite was not accepted, therefore the `Call.State` is not available.

It is important to call the disconnect() method to terminate the call. Not calling disconnect() results in leaked native resources and may lead to an out-of-memory crash. If the call is disconnected by the caller, callee, or Twilio, the SDK will automatically free native resources. However, disconnect() is an idempotent operation so it is best to call this method when you are certain your application no longer needs the object.

It is strongly recommended that Call instances are created and accessed from a single application thread. Accessing an instance from multiple threads may cause synchronization problems. Listeners are called on the thread that created the Call instance, unless the thread that created the Call instance does not have a Looper. In that case, the listener will be called on the application's main thread.

Insights :

The following connection events are reported to Insights during a Call

Group Name	Event Name	Description	Since version
connection	muted	The audio input of the `Call` is muted by calling `mute(boolean)` with `true`	3.0.0-beta2
connection	unmuted	The audio input of the `Call` is unmuted by calling `mute(boolean)` with `false`	3.0.0-beta2
connection	accepted-by-remote	The server returned an answer to the offer over the signaling channel	3.0.0-beta2
connection	ringing	The `Call` state transitions to `Call.State.RINGING`	3.0.0-beta2
connection	connected	The `Call` state transitions to `Call.State.CONNECTED`	3.0.0-beta2
connection	disconnect-called	The `disconnect()` method was called	3.0.0-beta2
connection	disconnected-by-local	The `Call` disconnected as a result of calling `disconnect()`. `Call.State` transitions to `Call.State.DISCONNECTED`	3.0.0-beta2
connection	disconnected-by-remote	The `Call` was disconnected by the server. `Call.State` transitions to `Call.State.DISCONNECTED`	3.0.0-beta2
connection	hold	The `Call` is on hold by calling `hold(boolean)`	3.0.0-beta2
connection	unhold	The `Call` is unhold by calling `hold(boolean)`	3.0.0-beta2
connection	error	Error description. The Call state transitions to `Call.State.DISCONNECTED`	3.0.0-beta2
connection	reconnecting	The `Call` is attempting to recover from a signaling or media connection interruption	3.0.0-beta3
connection	reconnected	The `Call` has recovered from a signaling or media connection interruption	3.0.0-beta3

The following ICE candidate event is reported to Insights during a Call

Group Name	Event Name	Description	Since version
ice-candidate	ice-candidate	ICE candidate events are raised when OnIceCandidate is called on the PeerConnection	4.1.0

The following ICE connection state events are reported to Insights during a Call

Group Name	Event Name	Description	Since version
ice-connection-state	new	The PeerConnection ice connection state changed to "new"	3.0.0-beta3
ice-connection-state	checking	The PeerConnection ice connection state changed to "checking"	3.0.0-beta3
ice-connection-state	connected	The PeerConnection ice connection state changed to "connected"	3.0.0-beta3
ice-connection-state	completed	The PeerConnection ice connection state changed to "completed"	3.0.0-beta3
ice-connection-state	closed	The PeerConnection ice connection state changed to “closed”	3.0.0-beta3
ice-connection-state	disconnected	The PeerConnection ice connection state changed to “disconnected”	3.0.0-beta3
ice-connection-state	failed	The PeerConnection ice connection state changed to “failed”	3.0.0-beta3

The following ICE gathering state events are reported to Insights during a Call

Group Name	Event Name	Description	Since version
ice-gathering-state	new	The PeerConnection ice gathering state changed to "new"	3.0.0-beta3
ice-gathering-state	gathering	The PeerConnection ice gathering state changed to "checking"	3.0.0-beta3
ice-gathering-state	complete	The PeerConnection ice gathering state changed to "connected"	3.0.0-beta3

The following signaling state events are reported to Insights during a Call

Group Name	Event Name	Description	Since version
signaling-state	stable	The PeerConnection signaling state changed to "stable"	3.0.0-beta3
signaling-state	have-local-offer	The PeerConnection signaling state changed to "have-local-offer"	3.0.0-beta3
signaling-state	have-remote-offers	The PeerConnection signaling state changed to "have-remote-offers"	3.0.0-beta3
signaling-state	have-local-pranswer	The PeerConnection signaling state changed to "have-local-pranswer"	3.0.0-beta3
signaling-state	have-remote-pranswer	The PeerConnection signaling state changed to “have-remote-pranswer”	3.0.0-beta3
signaling-state	closed	The PeerConnection signaling state changed to “closed”	3.0.0-beta3

The following network quality warning and network quality warning cleared events are reported to Insights during a Call

Group Name	Event Name	Description	Since version
network-quality-warning-raised	high-jitter	Three out of last five jitter samples exceed 30 ms	3.0.0-beta3
network-quality-warning-cleared	high-jitter	high-jitter warning cleared if last five jitter samples are less than 30 ms	3.0.0-beta3
network-quality-warning-raised	low-mos	Three out of last five mos samples are lower than 3	3.0.0-beta3
network-quality-warning-cleared	low-mos	low-mos cleared if last five mos samples are higher than 3	3.0.0-beta3
network-quality-warning-raised	high-packet-loss	Three out of last five packet loss samples show loss greater than 1%	3.0.0-beta3
network-quality-warning-cleared	high-packet-loss	high-packet-loss cleared if last five packet loss samples are lower than 1%	3.0.0-beta3
network-quality-warning-raised	high-rtt	Three out of last five RTT samples show greater than 400 ms	3.0.0-beta3
network-quality-warning-cleared	high-rtt	high-rtt warning cleared if last five RTT samples are lower than 400 ms	3.0.0-beta3

The following audio level warning and audio level warning cleared events are reported to Insights during a Call

Group Name	Event Name	Description	Since version
audio-level-warning-raised	constant-audio-input-level	Last ten audio input samples have the same audio level	3.0.0-beta3
audio-level-warning-cleared	constant-audio-input-level	constant-audio-input-level warning cleared if the current audio input level sample differs from the previous audio input level sample	3.0.0-beta3
audio-level-warning-raised	constant-audio-output-level	Last ten audio output samples have the same audio level	3.0.0-beta3
audio-level-warning-cleared	constant-audio-output-level	constant-audio-output-level warning cleared if the current audio output level sample differs from the previous audio output level sample	3.0.0-beta3

The following feedback events are reported to Insights during a Call

Group Name	Event Name	Description	Since version
feedback	received	`postFeedback(Score, Issue)` is called with a score other than `Call.Score.NOT_REPORTED` or an issue other than `Call.Issue.NOT_REPORTED` i	3.0.0-beta3
feedback	received-none	`postFeedback(Score, Issue)` is called with `Call.Score.NOT_REPORTED` and `Call.Issue.NOT_REPORTED`	3.0.0-beta3

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`Call.Issue` An enum representing issue type associated with a call.
`static interface`	`Call.Listener` Call.Listener interface defines a set of callbacks for events related to call.
`static class`	`Call.Score` An enum representing call quality score.
`static class`	`Call.State` An enum describing the possible states of a Call.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`disconnect()` Disconnects the Call.
`String`	`getFrom()` Returns the caller information when available.
`String`	`getSid()` Returns the call sid.
`Call.State`	`getState()` Returns the current state of the call.
`void`	`getStats(StatsListener statsListener)` Retrieve stats for all media tracks and notify `StatsListener` via calling thread.
`String`	`getTo()` Returns the callee information when available.
`void`	`hold(boolean hold)` Holds or un-holds the audio.
`boolean`	`isMuted()` Reports whether the audio input is muted.
`boolean`	`isOnHold()` Reports whether the call is on hold.
`void`	`mute(boolean mute)` Mutes or unmutes the audio input.
`void`	`postFeedback(Call.Score score, Call.Issue issue)` Posts the feedback collected for this call to Twilio.
`void`	`sendDigits(String digits)` Sends a string of DTMF digits.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getFrom
```
public String getFrom()
```
    Returns the caller information when available. The from field is null for an outgoing call and may be null if it was not provided in the CallInvite for an incoming call.
  - getTo
```
public String getTo()
```
    Returns the callee information when available. Returns null for an outgoing call.
  - getSid
```
public String getSid()
```
    Returns the call sid. The call sid is null until the call is in Call.State.RINGING state.
  - getState
```
public Call.State getState()
```
    Returns the current state of the call.
    Call is in Call.State.CONNECTING state when it is made or accepted.
    
    Call is in Call.State.RINGING state when it is ringing.
    
    Call transitions to Call.State.CONNECTED state when connected to Twilio.
    
    Call transitions to Call.State.DISCONNECTED state when disconnected.
    
    Returns:
    
    Provides the state of this call.
  - getStats
```
public void getStats(StatsListener statsListener)
```
    Retrieve stats for all media tracks and notify StatsListener via calling thread. In case where call is in Call.State.DISCONNECTED state, reports won't be delivered.
    
    Parameters:
    
    statsListener - listener that receives stats reports for all media tracks.
  - postFeedback
```
public void postFeedback(Call.Score score,
                         Call.Issue issue)
```
    Posts the feedback collected for this call to Twilio. If `0` `Score` and `not-reported` `Issue` are passed, Twilio will report feedback was not available for this call.
    
    Parameters:
    
    score - - the call quality score.
    
    issue - - the issue type associated with the call.
  - mute
```
public void mute(boolean mute)
```
    Mutes or unmutes the audio input.
  - sendDigits
```
public void sendDigits(String digits)
```
    Sends a string of DTMF digits.
    
    Parameters:
    
    digits - A string of digits to be sent. Valid values are "0" - "9", "*", "#", and "w". Each "w" will cause a 500 ms pause between digits sent.
  - hold
```
public void hold(boolean hold)
```
    Holds or un-holds the audio.
  - isMuted
```
public boolean isMuted()
```
    Reports whether the audio input is muted.
  - isOnHold
```
public boolean isOnHold()
```
    Reports whether the call is on hold.
  - disconnect
```
public void disconnect()
```
    Disconnects the Call.
    Invoking disconnect will result in a subsequent Call.Listener.onDisconnected(Call, CallException) being raised unless any of the following conditions are true:
    - Disconnect was already called on the call object. In this case, only one Call.Listener.onDisconnected(Call, CallException) will be raised
    - The call is already Call.State.DISCONNECTED
    - The call has been cancelled. In this case, the application has already received a MessageListener.onCancelledCallInvite(CancelledCallInvite, CallException) with a CancelledCallInvite with the same call SID of the call object

Class Call

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getFrom

getTo

getSid

getState

getStats

postFeedback

mute

sendDigits

hold

isMuted

isOnHold

disconnect