public final class Call extends Object
Modifier and Type | Class and Description |
---|---|
static class |
Call.Callback
Defines callbacks which inform the
InCallService of changes to a Call . |
static class |
Call.Details |
static class |
Call.Listener
Deprecated.
Use
Call.Callback instead. |
Modifier and Type | Field and Description |
---|---|
static String |
AVAILABLE_PHONE_ACCOUNTS
The key to retrieve the optional
PhoneAccount s Telecom can bundle with its Call
extras. |
static int |
STATE_ACTIVE
The state of a
Call when actively supporting conversation. |
static int |
STATE_CONNECTING
The initial state of an outgoing
Call . |
static int |
STATE_DIALING
The state of an outgoing
Call when dialing the remote number, but not yet connected. |
static int |
STATE_DISCONNECTED
The state of a
Call when no further voice or other communication is being
transmitted, the remote side has been or will inevitably be informed that the Call
is no longer active, and the local data transport has or inevitably will release resources
associated with this Call . |
static int |
STATE_DISCONNECTING
The state of a
Call when the user has initiated a disconnection of the call, but the
call has not yet been disconnected by the underlying ConnectionService . |
static int |
STATE_HOLDING
The state of a
Call when in a holding state. |
static int |
STATE_NEW
The state of a
Call when newly created. |
static int |
STATE_PRE_DIAL_WAIT
Deprecated.
use STATE_SELECT_PHONE_ACCOUNT.
|
static int |
STATE_PULLING_CALL
The state of an external call which is in the process of being pulled from a remote device to
the local device.
|
static int |
STATE_RINGING
The state of an incoming
Call when ringing locally, but not yet connected. |
static int |
STATE_SELECT_PHONE_ACCOUNT
The state of an outgoing
Call when waiting on user to select a
PhoneAccount through which to place the call. |
Modifier and Type | Method and Description |
---|---|
void |
addListener(Call.Listener listener)
Deprecated.
Use
registerCallback(android.telecom.Call.Callback) instead. |
void |
answer(int videoState)
Instructs this
STATE_RINGING Call to answer. |
void |
conference(Call callToConferenceWith)
Instructs this
Call to enter a conference. |
void |
disconnect()
Instructs this
Call to disconnect. |
List<String> |
getCannedTextResponses()
Obtains a list of canned, pre-configured message responses to present to the user as
ways of rejecting this
Call using via a text message. |
List<Call> |
getChildren()
Obtains the children of this conference
Call , if any. |
List<Call> |
getConferenceableCalls()
Returns the list of
Call s with which this Call is allowed to conference. |
Call.Details |
getDetails()
Obtains an object containing call details.
|
Call |
getParent()
Obtains the parent of this
Call in a conference, if any. |
String |
getRemainingPostDialSequence()
Obtains the post-dial sequence remaining to be emitted by this
Call , if any. |
int |
getState()
Obtains the state of this
Call . |
InCallService.VideoCall |
getVideoCall()
Obtains an object that can be used to display video from this
Call . |
void |
hold()
Instructs this
Call to go on hold. |
void |
mergeConference()
Merges the calls within this conference.
|
void |
phoneAccountSelected(PhoneAccountHandle accountHandle,
boolean setDefault)
Notifies this
Call that an account has been selected and to proceed with placing
an outgoing call. |
void |
playDtmfTone(char digit)
Instructs this
Call to play a dual-tone multi-frequency signaling (DTMF) tone. |
void |
postDialContinue(boolean proceed)
Instructs this
Call to continue playing a post-dial DTMF string. |
void |
pullExternalCall()
Initiates a request to the
ConnectionService to pull an external call to the local
device. |
void |
putExtra(String key,
boolean value)
Adds a boolean extra to this
Call . |
void |
putExtra(String key,
int value)
Adds an integer extra to this
Call . |
void |
putExtra(String key,
String value)
Adds a string extra to this
Call . |
void |
putExtras(Bundle extras)
Adds some extras to this
Call . |
void |
registerCallback(Call.Callback callback)
Registers a callback to this
Call . |
void |
registerCallback(Call.Callback callback,
Handler handler)
Registers a callback to this
Call . |
void |
reject(boolean rejectWithMessage,
String textMessage)
Instructs this
STATE_RINGING Call to reject. |
void |
removeExtras(List<String> keys)
Removes extras from this
Call . |
void |
removeExtras(String... keys)
Removes extras from this
Call . |
void |
removeListener(Call.Listener listener)
Deprecated.
Use
unregisterCallback(android.telecom.Call.Callback) instead. |
void |
sendCallEvent(String event,
Bundle extras)
|
void |
splitFromConference()
Instructs this
Call to split from any conference call with which it may be
connected. |
void |
stopDtmfTone()
Instructs this
Call to stop any dual-tone multi-frequency signaling (DTMF) tone
currently playing. |
void |
swapConference()
Swaps the calls within this conference.
|
String |
toString()
Returns a string representation of the object.
|
void |
unhold()
Instructs this
STATE_HOLDING call to release from hold. |
void |
unregisterCallback(Call.Callback callback)
Unregisters a callback from this
Call . |
public static final int STATE_NEW
Call
when newly created.public static final int STATE_DIALING
Call
when dialing the remote number, but not yet connected.public static final int STATE_RINGING
Call
when ringing locally, but not yet connected.public static final int STATE_HOLDING
Call
when in a holding state.public static final int STATE_ACTIVE
Call
when actively supporting conversation.public static final int STATE_DISCONNECTED
Call
when no further voice or other communication is being
transmitted, the remote side has been or will inevitably be informed that the Call
is no longer active, and the local data transport has or inevitably will release resources
associated with this Call
.public static final int STATE_SELECT_PHONE_ACCOUNT
Call
when waiting on user to select a
PhoneAccount
through which to place the call.@Deprecated public static final int STATE_PRE_DIAL_WAIT
public static final int STATE_CONNECTING
Call
.
Common transitions are to STATE_DIALING
state for a successful call or
STATE_DISCONNECTED
if it failed.public static final int STATE_DISCONNECTING
Call
when the user has initiated a disconnection of the call, but the
call has not yet been disconnected by the underlying ConnectionService
. The next
state of the call is (potentially) STATE_DISCONNECTED
.public static final int STATE_PULLING_CALL
A call can only be in this state if the Call.Details.PROPERTY_IS_EXTERNAL_CALL
property
and Call.Details.CAPABILITY_CAN_PULL_CALL
capability are set on the call.
An InCallService
will only see this state if it has the
TelecomManager.METADATA_INCLUDE_EXTERNAL_CALLS
metadata set to true
in its
manifest.
public static final String AVAILABLE_PHONE_ACCOUNTS
PhoneAccount
s Telecom can bundle with its Call
extras. Used to pass the phone accounts to display on the front end to the user in order to
select phone accounts to (for example) place a call.public String getRemainingPostDialSequence()
Call
, if any.null
if there is no post-dial sequence
remaining or this Call
is not in a post-dial state.public void answer(int videoState)
STATE_RINGING
Call
to answer.videoState
- The video state in which to answer the call.public void reject(boolean rejectWithMessage, String textMessage)
STATE_RINGING
Call
to reject.rejectWithMessage
- Whether to reject with a text message.textMessage
- An optional text message with which to respond.public void disconnect()
Call
to disconnect.public void hold()
Call
to go on hold.public void unhold()
STATE_HOLDING
call to release from hold.public void playDtmfTone(char digit)
Call
to play a dual-tone multi-frequency signaling (DTMF) tone.
Any other currently playing DTMF tone in the specified call is immediately stopped.digit
- A character representing the DTMF digit for which to play the tone. This
value must be one of '0'
through '9'
, '*'
or '#'
.public void stopDtmfTone()
Call
to stop any dual-tone multi-frequency signaling (DTMF) tone
currently playing.
DTMF tones are played by calling playDtmfTone(char)
. If no DTMF tone is
currently playing, this method will do nothing.public void postDialContinue(boolean proceed)
Call
to continue playing a post-dial DTMF string.
A post-dial DTMF string is a string of digits entered after a phone number, when dialed,
that are immediately sent as DTMF tones to the recipient as soon as the connection is made.
If the DTMF string contains a TelecomManager.DTMF_CHARACTER_PAUSE
symbol, this
Call
will temporarily pause playing the tones for a pre-defined period of time.
If the DTMF string contains a TelecomManager.DTMF_CHARACTER_WAIT
symbol, this
Call
will pause playing the tones and notify callbacks via
Call.Callback.onPostDialWait(Call, String)
. At this point, the in-call app
should display to the user an indication of this state and an affordance to continue
the postdial sequence. When the user decides to continue the postdial sequence, the in-call
app should invoke the postDialContinue(boolean)
method.proceed
- Whether or not to continue with the post-dial sequence.public void phoneAccountSelected(PhoneAccountHandle accountHandle, boolean setDefault)
Call
that an account has been selected and to proceed with placing
an outgoing call. Optionally sets this account as the default account.public void conference(Call callToConferenceWith)
Call
to enter a conference.callToConferenceWith
- The other call with which to conference.public void splitFromConference()
Call
to split from any conference call with which it may be
connected.public void mergeConference()
Call.Details.CAPABILITY_MERGE_CONFERENCE
.public void swapConference()
Call.Details.CAPABILITY_SWAP_CONFERENCE
.public void pullExternalCall()
ConnectionService
to pull an external call to the local
device.
Calls to this method are ignored if the call does not have the
Call.Details.PROPERTY_IS_EXTERNAL_CALL
property set.
An InCallService
will only see calls which support this method if it has the
TelecomManager.METADATA_INCLUDE_EXTERNAL_CALLS
metadata set to true
in its manifest.
public void sendCallEvent(String event, Bundle extras)
Call
event from this Call
to the associated Connection
in
the ConnectionService
.
Call events are used to communicate point in time information from an InCallService
to a ConnectionService
. A ConnectionService
implementation could define
events which enable the InCallService
, for example, toggle a unique feature of the
ConnectionService
.
A ConnectionService
can communicate to the InCallService
using
Connection.sendConnectionEvent(String, Bundle)
.
Events are exposed to ConnectionService
implementations via
Connection.onCallEvent(String, Bundle)
.
No assumptions should be made as to how a ConnectionService
will handle these events.
The InCallService
must assume that the ConnectionService
could chose to
ignore some events altogether.
Events should be fully qualified (e.g., com.example.event.MY_EVENT
) to avoid
conflicts between InCallService
implementations. Further, InCallService
implementations shall not re-purpose events in the android.*
namespace, nor shall
they define their own event types in this namespace. When defining a custom event type,
ensure the contents of the extras Bundle
is clearly defined. Extra keys for this
bundle should be named similar to the event type (e.g. com.example.extra.MY_EXTRA
).
When defining events and the associated extras, it is important to keep their behavior
consistent when the associated InCallService
is updated. Support for deprecated
events/extras should me maintained to ensure backwards compatibility with older
ConnectionService
implementations which were built to support the older behavior.
event
- The connection event.extras
- Bundle containing extra information associated with the event.public final void putExtras(Bundle extras)
Call
. Existing keys are replaced and new ones are
added.
No assumptions should be made as to how an In-Call UI or service will handle these extras. Keys should be fully qualified (e.g., com.example.MY_EXTRA) to avoid conflicts.
extras
- The extras to add.public final void putExtra(String key, boolean value)
Call
.key
- The extra key.value
- The value.public final void putExtra(String key, int value)
Call
.key
- The extra key.value
- The value.public final void putExtra(String key, String value)
Call
.key
- The extra key.value
- The value.public final void removeExtras(List<String> keys)
Call
.keys
- The keys of the extras to remove.public final void removeExtras(String... keys)
Call
.keys
- The keys of the extras to remove.public Call getParent()
Call
in a conference, if any.Call
, or null
if this Call
is not a
child of any conference Call
s.public List<Call> getChildren()
Call
, if any.Call
if this Call
is a conference, or an empty
List
otherwise.public List<Call> getConferenceableCalls()
Call
s with which this Call
is allowed to conference.Call
s.public int getState()
Call
.STATE_*
constants.public List<String> getCannedTextResponses()
Call
using via a text message.reject(boolean, String)
public InCallService.VideoCall getVideoCall()
Call
.Call.VideoCall
.public Call.Details getDetails()
Call.Details
object. Depending on the state of the Call
, the
result may be null
.public void registerCallback(Call.Callback callback)
Call
.callback
- A Callback
.public void registerCallback(Call.Callback callback, Handler handler)
Call
.callback
- A Callback
.handler
- A handler which command and status changes will be delivered to.public void unregisterCallback(Call.Callback callback)
Call
.callback
- A Callback
.public String toString()
Object
toString
method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString
method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@
', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())
@Deprecated public void addListener(Call.Listener listener)
registerCallback(android.telecom.Call.Callback)
instead.Call
.listener
- A Listener
.@Deprecated public void removeListener(Call.Listener listener)
unregisterCallback(android.telecom.Call.Callback)
instead.Call
.listener
- A Listener
.