public abstract class Connection extends Conferenceable
Implementations create a custom subclass of Connection
and return it to the framework
as the return value of
ConnectionService.onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)
or
ConnectionService.onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)
.
Implementations are then responsible for updating the state of the Connection
, and
must call destroy()
to signal to the framework that the Connection
is no
longer used and associated resources may be recovered.
Subclasses of Connection
override the on*
methods to provide the the
ConnectionService
's implementation of calling functionality. The on*
methods are
called by Telecom to inform an instance of a Connection
of actions specific to that
Connection
instance.
Basic call support requires overriding the following methods: onAnswer()
,
onDisconnect()
, onReject()
, onAbort()
Where a Connection
has CAPABILITY_SUPPORT_HOLD
, the onHold()
and
onUnhold()
methods should be overridden to provide hold support for the
Connection
.
Where a Connection
supports a variation of video calling (e.g. the
CAPABILITY_SUPPORTS_VT_*
capability bits), onAnswer(int)
should be overridden
to support answering a call as a video call.
Where a Connection
has PROPERTY_IS_EXTERNAL_CALL
and
CAPABILITY_CAN_PULL_CALL
, onPullExternalCall()
should be overridden to provide
support for pulling the external call.
Where a Connection
supports conference calling onSeparate()
should be
overridden.
There are a number of other on*
methods which a Connection
can choose to
implement, depending on whether it is concerned with the associated calls from Telecom. If,
for example, call events from a InCallService
are handled,
onCallEvent(String, Bundle)
should be overridden. Another example is
onExtrasChanged(Bundle)
, which should be overridden if the Connection
wishes to
make use of extra information provided via the Call.putExtras(Bundle)
and
Call.removeExtras(String...)
methods.
Modifier and Type | Class and Description |
---|---|
static class |
Connection.Listener |
static class |
Connection.VideoProvider
Provides a means of controlling the video session associated with a
Connection . |
Modifier and Type | Field and Description |
---|---|
static int |
CAPABILITY_CAN_PAUSE_VIDEO
For video calls, indicates whether the outgoing video for the call can be paused using
the
VideoProfile.STATE_PAUSED VideoState. |
static int |
CAPABILITY_CAN_PULL_CALL
When set for an external connection, indicates that this
Connection can be pulled
from a remote device to the current device. |
static int |
CAPABILITY_CAN_SEND_RESPONSE_VIA_CONNECTION
Indicates that the connection itself wants to handle any sort of reply response, rather than
relying on SMS.
|
static int |
CAPABILITY_CAN_UPGRADE_TO_VIDEO
Call can be upgraded to a video call.
|
static int |
CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO
When set, prevents a video call from being downgraded to an audio-only call.
|
static int |
CAPABILITY_CONFERENCE_HAS_NO_CHILDREN
For a conference, indicates the conference will not have child connections.
|
static int |
CAPABILITY_DISCONNECT_FROM_CONFERENCE
Connection is able to be individually disconnected when in a
Conference . |
static int |
CAPABILITY_HOLD
Connection can currently be put on hold or unheld.
|
static int |
CAPABILITY_MANAGE_CONFERENCE
Connection supports conference management.
|
static int |
CAPABILITY_MERGE_CONFERENCE
Connections within a conference can be merged.
|
static int |
CAPABILITY_MUTE
Connection can be muted.
|
static int |
CAPABILITY_RESPOND_VIA_TEXT
Connection supports responding via text option.
|
static int |
CAPABILITY_SEPARATE_FROM_CONFERENCE
Connection is able to be separated from its parent
Conference , if any. |
static int |
CAPABILITY_SPEED_UP_MT_AUDIO
Speed up audio setup for MT call.
|
static int |
CAPABILITY_SUPPORT_HOLD
Connection supports the hold feature.
|
static int |
CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL
Local device supports bidirectional video calling.
|
static int |
CAPABILITY_SUPPORTS_VT_LOCAL_RX
Local device supports receiving video.
|
static int |
CAPABILITY_SUPPORTS_VT_LOCAL_TX
Local device supports transmitting video.
|
static int |
CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL
Remote device supports bidirectional video calling.
|
static int |
CAPABILITY_SUPPORTS_VT_REMOTE_RX
Remote device supports receiving video.
|
static int |
CAPABILITY_SUPPORTS_VT_REMOTE_TX
Remote device supports transmitting video.
|
static int |
CAPABILITY_SWAP_CONFERENCE
Connections within a conference can be swapped between foreground and background.
|
static int |
CAPABILITY_UNUSED |
static int |
CAPABILITY_UNUSED_2
Un-used.
|
static int |
CAPABILITY_UNUSED_3
Un-used.
|
static int |
CAPABILITY_UNUSED_4
Un-used.
|
static int |
CAPABILITY_UNUSED_5
Un-used.
|
static String |
EVENT_CALL_MERGE_FAILED
Connection event used to inform
InCallService s when the merging of two calls has
failed. |
static String |
EVENT_CALL_PULL_FAILED
Connection event used to inform
InCallService s when pulling of an external call has
failed. |
static String |
EVENT_CALL_REMOTELY_HELD
Connection event used to inform
InCallService s when a call has been put on hold by
the remote party. |
static String |
EVENT_CALL_REMOTELY_UNHELD
Connection event used to inform
InCallService s when a call which was remotely held
(see EVENT_CALL_REMOTELY_HELD ) has been un-held by the remote party. |
static String |
EVENT_ON_HOLD_TONE_END
Connection event used to inform Telecom that it should stop the on hold tone.
|
static String |
EVENT_ON_HOLD_TONE_START
Connection event used to inform Telecom that it should play the on hold tone.
|
static String |
EXTRA_ANSWERING_DROPS_FG_CALL
Boolean connection extra key set on a
Connection in
STATE_RINGING state to indicate that answering the call will cause the
current active foreground call to be dropped. |
static String |
EXTRA_CALL_SUBJECT
Connection extra key used to store the subject for an incoming call.
|
static String |
EXTRA_CHILD_ADDRESS
Connection extra key used to store a child number associated with the current connection.
|
static String |
EXTRA_DISABLE_ADD_CALL
Boolean connection extra key on a
Connection which indicates that adding an
additional call is disallowed. |
static String |
EXTRA_LAST_FORWARDED_NUMBER
Connection extra key used to store the last forwarded number associated with the current
connection.
|
static String |
EXTRA_ORIGINAL_CONNECTION_ID
String connection extra key on a
Connection or Conference which contains the
original Connection ID associated with the connection. |
static int |
PROPERTY_EMERGENCY_CALLBACK_MODE
Indicates that the current device callback number should be shown.
|
static int |
PROPERTY_GENERIC_CONFERENCE
Whether the call is a generic conference, where we do not know the precise state of
participants in the conference (eg. on CDMA).
|
static int |
PROPERTY_HAS_CDMA_VOICE_PRIVACY
Indicates that the connection has CDMA Enhanced Voice Privacy enabled.
|
static int |
PROPERTY_HIGH_DEF_AUDIO
Connection is using high definition audio.
|
static int |
PROPERTY_IS_DOWNGRADED_CONFERENCE
Indicates that the connection represents a downgraded IMS conference.
|
static int |
PROPERTY_IS_EXTERNAL_CALL
When set, indicates that the
Connection does not actually exist locally for the
ConnectionService . |
static int |
PROPERTY_WIFI
Connection is using WIFI.
|
static int |
STATE_ACTIVE
A connection is active.
|
static int |
STATE_DIALING
An outgoing connection is in the dialing state.
|
static int |
STATE_DISCONNECTED
A connection has been disconnected.
|
static int |
STATE_HOLDING
A connection is on hold.
|
static int |
STATE_INITIALIZING
The connection is initializing.
|
static int |
STATE_NEW
The connection is new and not connected.
|
static int |
STATE_PULLING_CALL
The state of an external connection which is in the process of being pulled from a remote
device to the local device.
|
static int |
STATE_RINGING
An incoming connection is in the ringing state.
|
Constructor and Description |
---|
Connection()
Create a new Connection.
|
Modifier and Type | Method and Description |
---|---|
void |
addCapability(int capability)
Adds the specified capability to the set of capabilities of this
Connection . |
Connection |
addConnectionListener(Connection.Listener l)
Assign a listener to be notified of state changes.
|
boolean |
can(int capability)
Whether the capabilities of this
Connection supports the specified capability. |
static boolean |
can(int capabilities,
int capability)
Whether the given capabilities support the specified capability.
|
static String |
capabilitiesToString(int capabilities)
Renders a set of capability bits (
CAPABILITY_* ) as a human readable string. |
static String |
capabilitiesToStringShort(int capabilities)
Renders a set of capability bits (
CAPABILITY_* ) as a *short* human readable
string. |
void |
checkImmutable()
Override to throw an
UnsupportedOperationException if this Connection is
not intended to be mutated, e.g., if it is a marker for failure. |
static Connection |
createCanceledConnection()
Return a
Connection which represents a canceled connection attempt. |
static Connection |
createFailedConnection(DisconnectCause disconnectCause)
Return a
Connection which represents a failed connection attempt. |
void |
destroy()
Tears down the Connection object.
|
Uri |
getAddress() |
int |
getAddressPresentation() |
boolean |
getAudioModeIsVoip() |
AudioState |
getAudioState()
Deprecated.
Use
getCallAudioState() instead. |
CallAudioState |
getCallAudioState() |
String |
getCallerDisplayName() |
int |
getCallerDisplayNamePresentation() |
Conference |
getConference() |
List<Conferenceable> |
getConferenceables()
Returns the connections or conferences with which this connection can be conferenced.
|
int |
getConnectionCapabilities()
Returns the connection's capabilities, as a bit mask of the
CAPABILITY_* constants. |
int |
getConnectionProperties()
Returns the connection's properties, as a bit mask of the
PROPERTY_* constants. |
ConnectionService |
getConnectionService() |
long |
getConnectTimeMillis()
Retrieves the connection start time of the
Connnection , if specified. |
DisconnectCause |
getDisconnectCause() |
Bundle |
getExtras()
Returns the extras associated with this connection.
|
int |
getState() |
StatusHints |
getStatusHints() |
String |
getTelecomCallId()
Returns the Telecom internal call ID associated with this connection.
|
Connection.VideoProvider |
getVideoProvider() |
int |
getVideoState()
Returns the video state of the connection.
|
boolean |
isRingbackRequested()
Returns whether this connection is requesting that the system play a ringback tone
on its behalf.
|
protected void |
notifyConferenceMergeFailed()
Notifies listeners that the merge request failed.
|
protected void |
notifyConferenceStarted()
Notifies listeners that a conference call has been started.
|
protected void |
notifyConferenceSupportedChanged(boolean isConferenceSupported)
Notifies listeners when a change has occurred to the Connection which impacts its ability to
be a part of a conference call.
|
void |
onAbort()
Notifies this Connection of a request to abort.
|
void |
onAnswer()
Notifies this Connection, which is in
STATE_RINGING , of
a request to accept. |
void |
onAnswer(int videoState)
Notifies this Connection, which is in
STATE_RINGING , of
a request to accept. |
void |
onAudioStateChanged(AudioState state)
Deprecated.
Use
onCallAudioStateChanged(CallAudioState) instead. |
void |
onCallAudioStateChanged(CallAudioState state)
Notifies this Connection that the
getCallAudioState() property has a new value. |
void |
onCallEvent(String event,
Bundle extras)
Notifies this Connection of a
Call event initiated from an InCallService . |
void |
onDisconnect()
Notifies this Connection of a request to disconnect.
|
void |
onDisconnectConferenceParticipant(Uri endpoint)
Notifies this Connection of a request to disconnect a participant of the conference managed
by the connection.
|
void |
onExtrasChanged(Bundle extras)
Notifies this
Connection of a change to the extras made outside the
ConnectionService . |
void |
onHold()
Notifies this Connection of a request to hold.
|
void |
onPlayDtmfTone(char c)
Notifies this Connection of a request to play a DTMF tone.
|
void |
onPostDialContinue(boolean proceed)
Notifies this Connection whether the user wishes to proceed with the post-dial DTMF codes.
|
void |
onPullExternalCall()
Notifies this Connection of a request to pull an external call to the local device.
|
void |
onReject()
Notifies this Connection, which is in
STATE_RINGING , of
a request to reject. |
void |
onReject(String replyMessage)
Notifies this Connection, which is in
STATE_RINGING , of
a request to reject with a message. |
void |
onSeparate()
Notifies this Connection of a request to separate from its parent conference.
|
void |
onSilence()
Notifies the Connection of a request to silence the ringer.
|
void |
onStateChanged(int state)
Notifies this Connection of an internal state change.
|
void |
onStopDtmfTone()
Notifies this Connection of a request to stop any currently playing DTMF tones.
|
void |
onUnhold()
Notifies this Connection of a request to exit a hold state.
|
static String |
propertiesToString(int properties)
Renders a set of property bits (
PROPERTY_* ) as a human readable string. |
static String |
propertiesToStringShort(int properties)
Renders a set of property bits (
PROPERTY_* ) as a *short* human readable string. |
void |
putExtra(String key,
boolean value)
Adds a boolean extra to this
Connection . |
void |
putExtra(String key,
int value)
Adds an integer extra to this
Connection . |
void |
putExtra(String key,
String value)
Adds a string extra to this
Connection . |
void |
putExtras(Bundle extras)
Adds some extras to this
Connection . |
void |
removeCapability(int capability)
Removes the specified capability from the set of capabilities of this
Connection . |
Connection |
removeConnectionListener(Connection.Listener l)
Remove a previously assigned listener that was being notified of state changes.
|
void |
removeExtras(List<String> keys)
Removes extras from this
Connection . |
void |
removeExtras(String... keys)
Removes extras from this
Connection . |
void |
resetConference()
Resets the conference that this connection is a part of.
|
void |
sendConnectionEvent(String event,
Bundle extras)
Sends an event associated with this
Connection with associated event extras to the
InCallService . |
void |
setActive()
Sets state to active (e.g., an ongoing connection where two or more parties can actively
communicate).
|
void |
setAddress(Uri address,
int presentation)
Sets the value of the
getAddress() property. |
void |
setAudioModeIsVoip(boolean isVoip)
Requests that the framework use VOIP audio mode for this connection.
|
void |
setCallerDisplayName(String callerDisplayName,
int presentation)
Sets the caller display name (CNAP).
|
boolean |
setConference(Conference conference)
Sets the conference that this connection is a part of.
|
void |
setConferenceableConnections(List<Connection> conferenceableConnections)
Sets the connections with which this connection can be conferenced.
|
void |
setConferenceables(List<Conferenceable> conferenceables)
Similar to
setConferenceableConnections(java.util.List) , sets a list of connections
or conferences with which this connection can be conferenced. |
void |
setConnectionCapabilities(int connectionCapabilities)
Sets the connection's capabilities as a bit mask of the
CAPABILITY_* constants. |
void |
setConnectionProperties(int connectionProperties)
Sets the connection's properties as a bit mask of the
PROPERTY_* constants. |
void |
setConnectionService(ConnectionService connectionService) |
void |
setConnectTimeMillis(long connectTimeMillis)
Sets the time at which a call became active on this Connection.
|
void |
setDialing()
Sets state to dialing (e.g., dialing an outbound connection).
|
void |
setDisconnected(DisconnectCause disconnectCause)
Sets state to disconnected.
|
void |
setExtras(Bundle extras)
Set some extras that can be associated with this
Connection . |
void |
setInitialized()
Sets state to initialized (the Connection has been set up and is now ready to be used).
|
void |
setInitializing()
Sets state to initializing (this Connection is not yet ready to be used).
|
void |
setNextPostDialChar(char nextChar)
Informs listeners that this
Connection has processed a character in the post-dial
started state. |
void |
setOnHold()
Sets state to be on hold.
|
void |
setPostDialWait(String remaining)
Informs listeners that this
Connection is in a post-dial wait state. |
void |
setPulling()
Sets state to pulling (e.g. the connection is being pulled to the local device from another
device).
|
void |
setRingbackRequested(boolean ringback)
Requests that the framework play a ringback tone.
|
void |
setRinging()
Sets state to ringing (e.g., an inbound ringing connection).
|
void |
setStatusHints(StatusHints statusHints)
Sets the label and icon status to display in the in-call UI.
|
void |
setTelecomCallId(String callId)
Sets the telecom call ID associated with this Connection.
|
void |
setVideoProvider(Connection.VideoProvider videoProvider)
Sets the video connection provider.
|
void |
setVideoState(int videoState)
Set the video state for the connection.
|
static String |
stateToString(int state) |
void |
unsetConnectionService(ConnectionService connectionService) |
protected void |
updateConferenceParticipants(List<ConferenceParticipant> conferenceParticipants)
Notifies listeners of a change to conference participant(s).
|
public static final int STATE_INITIALIZING
Connection
returned by a ConnectionService
.public static final int STATE_NEW
public static final int STATE_RINGING
public static final int STATE_DIALING
public static final int STATE_ACTIVE
public static final int STATE_HOLDING
public static final int STATE_DISCONNECTED
public static final int STATE_PULLING_CALL
A connection can only be in this state if the PROPERTY_IS_EXTERNAL_CALL
property and
CAPABILITY_CAN_PULL_CALL
capability bits are set on the connection.
public static final int CAPABILITY_HOLD
CAPABILITY_SUPPORT_HOLD
in that although a connection may support 'hold' most times,
it does not at the moment support the function. This can be true while the call is in the
state STATE_DIALING
, for example. During this condition, an in-call UI may
display a disabled 'hold' button.public static final int CAPABILITY_SUPPORT_HOLD
public static final int CAPABILITY_MERGE_CONFERENCE
ConnectionService
has the option to
add a Conference
before the child Connection
s are merged. This is how
CDMA-based Connection
s are implemented. For these unmerged Conference
s, this
capability allows a merge button to be shown while the conference is in the foreground
of the in-call UI.
This is only intended for use by a Conference
.
public static final int CAPABILITY_SWAP_CONFERENCE
CAPABILITY_MERGE_CONFERENCE
for additional information.
This is only intended for use by a Conference
.
public static final int CAPABILITY_UNUSED
public static final int CAPABILITY_RESPOND_VIA_TEXT
public static final int CAPABILITY_MUTE
public static final int CAPABILITY_MANAGE_CONFERENCE
Conference
s which can have Connection
s as children.public static final int CAPABILITY_SUPPORTS_VT_LOCAL_RX
public static final int CAPABILITY_SUPPORTS_VT_LOCAL_TX
public static final int CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL
public static final int CAPABILITY_SUPPORTS_VT_REMOTE_RX
public static final int CAPABILITY_SUPPORTS_VT_REMOTE_TX
public static final int CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL
public static final int CAPABILITY_SEPARATE_FROM_CONFERENCE
Conference
, if any.public static final int CAPABILITY_DISCONNECT_FROM_CONFERENCE
Conference
.public static final int CAPABILITY_UNUSED_2
public static final int CAPABILITY_UNUSED_3
public static final int CAPABILITY_UNUSED_4
public static final int CAPABILITY_UNUSED_5
public static final int CAPABILITY_SPEED_UP_MT_AUDIO
public static final int CAPABILITY_CAN_UPGRADE_TO_VIDEO
public static final int CAPABILITY_CAN_PAUSE_VIDEO
VideoProfile.STATE_PAUSED
VideoState.public static final int CAPABILITY_CONFERENCE_HAS_NO_CHILDREN
An example of a conference with child connections is a GSM conference call, where the radio retains connections to the individual participants of the conference. Another example is an IMS conference call where conference event package functionality is supported; in this case the conference server ensures the radio is aware of the participants in the conference, which are represented by child connections.
An example of a conference with no child connections is an IMS conference call with no conference event package support. Such a conference is represented by the radio as a single connection to the IMS conference server.
Indicating whether a conference has children or not is important to help user interfaces visually represent a conference. A conference with no children, for example, will have the conference connection shown in the list of calls on a Bluetooth device, where if the conference has children, only the children will be shown in the list of calls on a Bluetooth device.
public static final int CAPABILITY_CAN_SEND_RESPONSE_VIA_CONNECTION
public static final int CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO
Should be set when the VideoState has the VideoProfile.STATE_TX_ENABLED
or
VideoProfile.STATE_RX_ENABLED
bits set to indicate that the connection cannot be
downgraded from a video call back to a VideoState of
VideoProfile.STATE_AUDIO_ONLY
.
Intuitively, a call which can be downgraded to audio should also have local and remote
video
capabilities (see CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL
and
CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL
).
public static final int CAPABILITY_CAN_PULL_CALL
Connection
can be pulled
from a remote device to the current device.
Should only be set on a Connection
where PROPERTY_IS_EXTERNAL_CALL
is set.
public static final int PROPERTY_EMERGENCY_CALLBACK_MODE
public static final int PROPERTY_GENERIC_CONFERENCE
public static final int PROPERTY_HIGH_DEF_AUDIO
public static final int PROPERTY_WIFI
public static final int PROPERTY_IS_EXTERNAL_CALL
Connection
does not actually exist locally for the
ConnectionService
.
Consider, for example, a scenario where a user has two devices with the same phone number.
When a user places a call on one devices, the telephony stack can represent that call on the
other device by adding is to the ConnectionService
with the
PROPERTY_IS_EXTERNAL_CALL
capability set.
An ConnectionService
should not assume that all InCallService
s will handle
external connections. Only those InCallService
s which have the
TelecomManager.METADATA_INCLUDE_EXTERNAL_CALLS
metadata set to true
in its
manifest will see external connections.
public static final int PROPERTY_HAS_CDMA_VOICE_PRIVACY
public static final int PROPERTY_IS_DOWNGRADED_CONFERENCE
public static final String EXTRA_LAST_FORWARDED_NUMBER
public static final String EXTRA_CHILD_ADDRESS
PhoneAccount
's primary
address.public static final String EXTRA_CALL_SUBJECT
PhoneAccount
supports the capability PhoneAccount.CAPABILITY_CALL_SUBJECT
.public static final String EXTRA_ANSWERING_DROPS_FG_CALL
Connection
in
STATE_RINGING
state to indicate that answering the call will cause the
current active foreground call to be dropped.public static final String EXTRA_DISABLE_ADD_CALL
Connection
which indicates that adding an
additional call is disallowed.public static final String EXTRA_ORIGINAL_CONNECTION_ID
Connection
or Conference
which contains the
original Connection ID associated with the connection. Used in
RemoteConnectionService
to track the Connection ID which was originally assigned to a
connection/conference added via
ConnectionService.addExistingConnection(PhoneAccountHandle, Connection)
and
ConnectionService.addConference(Conference)
APIs. This is important to pass to
Telecom for when it deals with RemoteConnections. When the ConnectionManager wraps the
RemoteConnection
and RemoteConference
and adds it to Telecom, there needs to
be a way to ensure that we don't add the connection again as a duplicate.
For example, the TelephonyCS calls addExistingConnection for a Connection with ID
TelephonyCS@1
. The ConnectionManager learns of this via
ConnectionService.onRemoteExistingConnectionAdded(RemoteConnection)
, and wraps this
in a new Connection
which it adds to Telecom via
ConnectionService.addExistingConnection(PhoneAccountHandle, Connection)
. As part of
this process, the wrapped RemoteConnection gets assigned a new ID (e.g. ConnMan@1
).
The TelephonyCS will ALSO try to add the existing connection to Telecom, except with the
ID it originally referred to the connection as. Thus Telecom needs to know that the
Connection with ID ConnMan@1
is really the same as TelephonyCS@1
.
public static final String EVENT_ON_HOLD_TONE_START
sendConnectionEvent(String, Bundle)
.public static final String EVENT_ON_HOLD_TONE_END
sendConnectionEvent(String, Bundle)
.public static final String EVENT_CALL_PULL_FAILED
InCallService
s when pulling of an external call has
failed. The user interface should inform the user of the error.
Expected to be used by the ConnectionService
when the Call.pullExternalCall()
API is called on a Call
with the properties
Call.Details.PROPERTY_IS_EXTERNAL_CALL
and
Call.Details.CAPABILITY_CAN_PULL_CALL
, but the ConnectionService
could not
pull the external call due to an error condition.
Sent via sendConnectionEvent(String, Bundle)
. The Bundle
parameter is
expected to be null when this connection event is used.
public static final String EVENT_CALL_MERGE_FAILED
InCallService
s when the merging of two calls has
failed. The User Interface should use this message to inform the user of the error.
Sent via sendConnectionEvent(String, Bundle)
. The Bundle
parameter is
expected to be null when this connection event is used.
public static final String EVENT_CALL_REMOTELY_HELD
InCallService
s when a call has been put on hold by
the remote party.
This is different than the STATE_HOLDING
state which indicates that the
call is being held locally on the device. When a capable ConnectionService
receives
signalling to indicate that the remote party has put the call on hold, it can send this
connection event.
public static final String EVENT_CALL_REMOTELY_UNHELD
InCallService
s when a call which was remotely held
(see EVENT_CALL_REMOTELY_HELD
) has been un-held by the remote party.
This is different than the STATE_HOLDING
state which indicates that the
call is being held locally on the device. When a capable ConnectionService
receives
signalling to indicate that the remote party has taken the call off hold, it can send this
connection event.
public static boolean can(int capabilities, int capability)
capabilities
- A capability bit field.capability
- The capability to check capabilities for.public boolean can(int capability)
Connection
supports the specified capability.capability
- The capability to check capabilities for.public void removeCapability(int capability)
Connection
.capability
- The capability to remove from the set.public void addCapability(int capability)
Connection
.capability
- The capability to add to the set.public static String capabilitiesToString(int capabilities)
CAPABILITY_*
) as a human readable string.capabilities
- A capability bit field.public static String capabilitiesToStringShort(int capabilities)
CAPABILITY_*
) as a *short* human readable
string.capabilities
- A capability bit field.public static String propertiesToString(int properties)
PROPERTY_*
) as a human readable string.properties
- A property bit field.public static String propertiesToStringShort(int properties)
PROPERTY_*
) as a *short* human readable string.properties
- A property bit field.public final String getTelecomCallId()
public final Uri getAddress()
public final int getAddressPresentation()
TelecomManager
for valid values.public final String getCallerDisplayName()
public final int getCallerDisplayNamePresentation()
TelecomManager
for valid values.public final int getState()
public final int getVideoState()
VideoProfile.STATE_AUDIO_ONLY
,
VideoProfile.STATE_BIDIRECTIONAL
,
VideoProfile.STATE_TX_ENABLED
,
VideoProfile.STATE_RX_ENABLED
.@Deprecated public final AudioState getAudioState()
getCallAudioState()
instead.null
if this Connection
does not directly know about its audio state.public final CallAudioState getCallAudioState()
null
if this Connection
does not directly know about its audio state.public final Conference getConference()
public final boolean isRingbackRequested()
public final boolean getAudioModeIsVoip()
public final long getConnectTimeMillis()
Connnection
, if specified. A value of
Conference.CONNECT_TIME_NOT_SPECIFIED
indicates that Telecom should determine the
start time of the conference.Connnection
was connected.public final StatusHints getStatusHints()
public final Bundle getExtras()
Extras should be updated using putExtras(Bundle)
.
Telecom or an InCallService
can also update the extras via
Call.putExtras(Bundle)
, and
Call.removeExtras(List)
.
The connection is notified of changes to the extras made by Telecom or an
InCallService
by onExtrasChanged(Bundle)
.
public final Connection addConnectionListener(Connection.Listener l)
l
- A listener.public final Connection removeConnectionListener(Connection.Listener l)
l
- A Listener.public final DisconnectCause getDisconnectCause()
DisconnectCause
for this connection.public void setTelecomCallId(String callId)
callId
- The telecom call ID.public static String stateToString(int state)
state
- An integer value of a STATE_*
constant.public final int getConnectionCapabilities()
CAPABILITY_*
constants.public final int getConnectionProperties()
PROPERTY_*
constants.public final void setAddress(Uri address, int presentation)
getAddress()
property.address
- The new address.presentation
- The presentation requirements for the address.
See TelecomManager
for valid values.public final void setCallerDisplayName(String callerDisplayName, int presentation)
callerDisplayName
- The new display name.presentation
- The presentation requirements for the handle.
See TelecomManager
for valid values.public final void setVideoState(int videoState)
VideoProfile.STATE_AUDIO_ONLY
,
VideoProfile.STATE_BIDIRECTIONAL
,
VideoProfile.STATE_TX_ENABLED
,
VideoProfile.STATE_RX_ENABLED
.videoState
- The new video state.public final void setActive()
public final void setRinging()
public final void setInitializing()
public final void setInitialized()
public final void setDialing()
public final void setPulling()
Connection
s with
PROPERTY_IS_EXTERNAL_CALL
and CAPABILITY_CAN_PULL_CALL
.public final void setOnHold()
public final void setVideoProvider(Connection.VideoProvider videoProvider)
videoProvider
- The video provider.public final Connection.VideoProvider getVideoProvider()
public final void setDisconnected(DisconnectCause disconnectCause)
disconnectCause
- The reason for the disconnection, as specified by
DisconnectCause
.public final void setPostDialWait(String remaining)
Connection
is in a post-dial wait state. This is done
when (a) the Connection
is issuing a DTMF sequence; (b) it has encountered a "wait"
character; and (c) it wishes to inform the In-Call app that it is waiting for the end-user
to send an onPostDialContinue(boolean)
signal.remaining
- The DTMF character sequence remaining to be emitted once the
onPostDialContinue(boolean)
is received, including any "wait" characters
that remaining sequence may contain.public final void setNextPostDialChar(char nextChar)
Connection
has processed a character in the post-dial
started state. This is done when (a) the Connection
is issuing a DTMF sequence;
and (b) it wishes to signal Telecom to play the corresponding DTMF tone locally.nextChar
- The DTMF character that was just processed by the Connection
.public final void setRingbackRequested(boolean ringback)
ringback
- Whether the ringback tone is to be played.public final void setConnectionCapabilities(int connectionCapabilities)
CAPABILITY_*
constants.connectionCapabilities
- The new connection capabilities.public final void setConnectionProperties(int connectionProperties)
PROPERTY_*
constants.connectionProperties
- The new connection properties.public final void destroy()
public final void setAudioModeIsVoip(boolean isVoip)
isVoip
- True if the audio mode is VOIP.public final void setConnectTimeMillis(long connectTimeMillis)
connectionTimeMillis
- The connection time, in milliseconds.public final void setStatusHints(StatusHints statusHints)
statusHints
- The status label and icon to set.public final void setConferenceableConnections(List<Connection> conferenceableConnections)
conferenceableConnections
- The set of connections this connection can conference with.public final void setConferenceables(List<Conferenceable> conferenceables)
setConferenceableConnections(java.util.List)
, sets a list of connections
or conferences with which this connection can be conferenced.conferenceables
- The conferenceables.public final List<Conferenceable> getConferenceables()
public final void setConnectionService(ConnectionService connectionService)
public final void unsetConnectionService(ConnectionService connectionService)
public final ConnectionService getConnectionService()
public final boolean setConference(Conference conference)
resetConference()
to un-set the conference first.conference
- The conference.true
if the conference was successfully set.public final void resetConference()
public final void setExtras(Bundle extras)
Connection
.
New or existing keys are replaced in the Connection
extras. Keys which are no longer
in the new extras, but were present the last time setExtras
was called are removed.
Alternatively you may use the putExtras(Bundle)
, and
removeExtras(String...)
methods to modify the extras.
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 associated with this Connection
.public final void putExtras(Bundle extras)
Connection
. 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)
Connection
.key
- The extra key.value
- The value.public final void putExtra(String key, int value)
Connection
.key
- The extra key.value
- The value.public final void putExtra(String key, String value)
Connection
.key
- The extra key.value
- The value.public final void removeExtras(List<String> keys)
Connection
.keys
- The keys of the extras to remove.public final void removeExtras(String... keys)
Connection
.keys
- The keys of the extras to remove.@Deprecated public void onAudioStateChanged(AudioState state)
onCallAudioStateChanged(CallAudioState)
instead.getAudioState()
property has a new value.state
- The new connection audio state.public void onCallAudioStateChanged(CallAudioState state)
getCallAudioState()
property has a new value.state
- The new connection audio state.public void onStateChanged(int state)
state
- The new state, one of the STATE_*
constants.public void onPlayDtmfTone(char c)
c
- A DTMF character.public void onStopDtmfTone()
public void onDisconnect()
public void onDisconnectConferenceParticipant(Uri endpoint)
endpoint
- the Uri
of the participant to disconnect.public void onSeparate()
public void onAbort()
public void onHold()
public void onUnhold()
public void onAnswer(int videoState)
STATE_RINGING
, of
a request to accept.videoState
- The video state in which to answer the connection.public void onAnswer()
STATE_RINGING
, of
a request to accept.public void onReject()
STATE_RINGING
, of
a request to reject.public void onReject(String replyMessage)
STATE_RINGING
, of
a request to reject with a message.public void onSilence()
public void onPostDialContinue(boolean proceed)
public void onPullExternalCall()
The InCallService
issues a request to pull an external call to the local device via
Call.pullExternalCall()
.
For a Connection to be pulled, both the CAPABILITY_CAN_PULL_CALL
capability and PROPERTY_IS_EXTERNAL_CALL
property bits must be set.
For more information on external calls, see PROPERTY_IS_EXTERNAL_CALL
.
public void onCallEvent(String event, Bundle extras)
Call
event initiated from an InCallService
.
The InCallService
issues a Call event via Call.sendCallEvent(String, Bundle)
.
Where possible, the Connection should make an attempt to handle Call
events which
are part of the android.telecom.*
namespace. The Connection should ignore any events
it does not wish to handle. Unexpected events should be handled gracefully, as it is
possible that a InCallService
has defined its own Call events which a Connection is
not aware of.
See also Call.sendCallEvent(String, Bundle)
.
event
- The call event.extras
- Extras associated with the call event.public void onExtrasChanged(Bundle extras)
Connection
of a change to the extras made outside the
ConnectionService
.
These extras changes can originate from Telecom itself, or from an InCallService
via
the Call.putExtras(Bundle)
and
Call.removeExtras(List)
.
extras
- The new extras bundle.public static Connection createFailedConnection(DisconnectCause disconnectCause)
Connection
which represents a failed connection attempt. The returned
Connection
will have a DisconnectCause
and as specified,
and a getState()
of STATE_DISCONNECTED
.
The returned Connection
can be assumed to destroy()
itself when appropriate,
so users of this method need not maintain a reference to its return value to destroy it.
disconnectCause
- The disconnect cause, (android.telecomm.DisconnectCause
).Connection
which indicates failure.public void checkImmutable()
UnsupportedOperationException
if this Connection
is
not intended to be mutated, e.g., if it is a marker for failure. Only for framework use;
this should never be un-@hide-den.public static Connection createCanceledConnection()
Connection
which represents a canceled connection attempt. The returned
Connection
will have state STATE_DISCONNECTED
, and cannot be moved out of
that state. This connection should not be used for anything, and no other
Connection
s should be attempted.
so users of this method need not maintain a reference to its return value to destroy it.
Connection
which indicates that the underlying connection should
be canceled.protected final void notifyConferenceMergeFailed()
protected final void updateConferenceParticipants(List<ConferenceParticipant> conferenceParticipants)
conferenceParticipants
- The participants.protected void notifyConferenceStarted()
protected void notifyConferenceSupportedChanged(boolean isConferenceSupported)
isConferenceSupported
- true
if the connection supports being part of a
conference call, false
otherwise.public void sendConnectionEvent(String event, Bundle extras)
Connection
with associated event extras to the
InCallService
.
Connection events are used to communicate point in time information from a
ConnectionService
to a InCallService
implementations. An example of a
custom connection event includes notifying the UI when a WIFI call has been handed over to
LTE, which the InCall UI might use to inform the user that billing charges may apply. The
Android Telephony framework will send the EVENT_CALL_MERGE_FAILED
connection event
when a call to Call.mergeConference()
has failed to complete successfully. A
connection event could also be used to trigger UI in the InCallService
which prompts
the user to make a choice (e.g. whether they want to incur roaming costs for making a call),
which is communicated back via Call.sendCallEvent(String, Bundle)
.
Events are exposed to InCallService
implementations via
Call.Callback.onConnectionEvent(Call, String, Bundle)
.
No assumptions should be made as to how an In-Call UI or service will handle these events.
The ConnectionService
must assume that the In-Call UI could even chose to ignore
some events altogether.
Events should be fully qualified (e.g. com.example.event.MY_EVENT
) to avoid
conflicts between ConnectionService
implementations. Further, custom
ConnectionService
implementations shall not re-purpose events in the
android.*
namespace, nor shall they define new 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 ConnectionService
is updated. Support for deprecated
events/extras should me maintained to ensure backwards compatibility with older
InCallService
implementations which were built to support the older behavior.
event
- The connection event.extras
- Optional bundle containing extra information associated with the event.