Added in API level 23

Conference

abstract class Conference : Conferenceable
kotlin.Any
   ↳ android.telecom.Conferenceable
   ↳ android.telecom.Conference

Represents a conference call which can contain any number of Connection objects.

Summary

Constants
static Long

Used to indicate that the conference connection time is not specified.

Public constructors

Constructs a new Conference with a mandatory PhoneAccountHandle

Public methods
Boolean
addConnection(connection: Connection!)

Adds the specified connection as a child of this conference.

open static Conference
createFailedConference(disconnectCause: DisconnectCause, phoneAccount: PhoneAccountHandle)

Return a Conference which represents a failed conference attempt.

Unit

Tears down the conference object and any of its current connections.

CallAudioState!

MutableList<Connection!>!

Returns the connections with which this connection can be conferenced.

Int

Returns the capabilities of the conference.

Int

Returns the properties of the conference.

Long

Retrieves the connection start time of the Conference, if specified.

Long

Retrieves the connection start time of the Conference, if specified.

MutableList<Connection!>!

Returns the list of connections currently associated with the conference call.

CallEndpoint

Obtains the current CallEndpoint.

DisconnectCause!

Bundle!

Returns the extras associated with this conference.

PhoneAccountHandle!

Returns the PhoneAccountHandle the conference call is being placed through.

Int

Gets the state of the conference call.

StatusHints!

open Connection.VideoProvider!

Returns VideoProvider of the primary call.

open Int

Returns video state of the primary call.

Boolean

Returns whether this conference is requesting that the system play a ringback tone on its behalf.

open Unit

Notifies the Conference of a request to add a new participants to the conference call

open Unit
onAnswer(videoState: Int)

Notifies this Conference, which is in STATE_RINGING, of a request to accept.

open Unit

Notifies the Conference that the available call endpoints have been changed.

open Unit

Notifies the Conference that the getCallAudioState() property has a new value.

open Unit

Notifies the Conference that the audio endpoint has been changed.

open Unit

Notifies the Conference that a Connection has been added to it.

open Unit

Notifies the Conference when the Conference and all it's Connections should be disconnected.

open Unit

Notifies this Conference of a change to the extras made outside the ConnectionService.

open Unit

Notifies the Conference when it should be put on hold.

open Unit
onMerge(connection: Connection!)

Notifies the Conference when the specified Connection should merged with the conference call.

open Unit

Notifies the Conference when the child calls should be merged.

open Unit

Notifies the Conference that its audio mute state has been changed.

open Unit

Notifies the Conference of a request to play a DTMF tone.

open Unit

Notifies this Conference, which is in STATE_RINGING, of a request to reject.

open Unit
onSeparate(connection: Connection!)

Notifies the Conference when the specified Connection should be separated from the conference call.

open Unit

Notifies the Conference of a request to stop any currently playing DTMF tones.

open Unit

Notifies the Conference when the child calls should be swapped.

open Unit

Notifies the Conference when it should be moved from a held to active state.

Unit
putExtras(extras: Bundle)

Adds some extras to this Conference.

Unit

Removes the specified connection as a child of this conference.

Unit

Removes extras from this Conference.

Unit
removeExtras(vararg keys: String!)

Removes extras from this Conference.

open Unit
sendConferenceEvent(event: String, extras: Bundle?)

Sends an event associated with this Conference with associated event extras to the InCallService.

Unit

Sets state to be active.

Unit
setConferenceableConnections(conferenceableConnections: MutableList<Connection!>!)

Sets the connections with which this connection can be conferenced.

Unit
setConnectionCapabilities(connectionCapabilities: Int)

Sets the capabilities of a conference.

Unit
setConnectionProperties(connectionProperties: Int)

Sets the properties of a conference.

Unit
setConnectionStartElapsedRealTime(connectionStartElapsedRealTime: Long)

Sets the start time of the Conference which is the basis for the determining the duration of the Conference.

Unit
setConnectionStartElapsedRealtimeMillis(connectionStartElapsedRealTime: Long)

Sets the start time of the Conference which is the basis for the determining the duration of the Conference.

Unit
setConnectionTime(connectionTimeMillis: Long)

Sets the connection start time of the Conference.

Unit

Sets state to be dialing.

Unit
setDisconnected(disconnectCause: DisconnectCause!)

Sets state to disconnected.

Unit
setExtras(extras: Bundle?)

Replaces all the extras associated with this Conference.

Unit

Sets state to be on hold.

Unit

Requests that the framework play a ringback tone.

Unit

Sets state to be ringing.

Unit
setStatusHints(statusHints: StatusHints!)

Sets the label and icon status to display in the InCall UI.

Unit

Sets the video connection provider.

Unit
setVideoState(c: Connection!, videoState: Int)

Set the video state for the conference.

open String

Constants

CONNECT_TIME_NOT_SPECIFIED

Added in API level 23
static val CONNECT_TIME_NOT_SPECIFIED: Long

Used to indicate that the conference connection time is not specified. If not specified, Telecom will set the connect time.

Value: 0L

Public constructors

Conference

Added in API level 23
Conference(phoneAccount: PhoneAccountHandle!)

Constructs a new Conference with a mandatory PhoneAccountHandle

Parameters
phoneAccount PhoneAccountHandle!: The PhoneAccountHandle associated with the conference.

Public methods

addConnection

Added in API level 23
fun addConnection(connection: Connection!): Boolean

Adds the specified connection as a child of this conference.

Parameters
connection Connection!: The connection to add.
Return
Boolean True if the connection was successfully added.

createFailedConference

Added in API level 31
open static fun createFailedConference(
    disconnectCause: DisconnectCause,
    phoneAccount: PhoneAccountHandle
): Conference

Return a Conference which represents a failed conference attempt. The returned Conference will have a android.telecom.DisconnectCause and as specified, and a getState() of STATE_DISCONNECTED.

The returned Conference 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.

Parameters
disconnectCause DisconnectCause: The disconnect cause, ({@see android.telecomm.DisconnectCause}). This value cannot be null.
phoneAccount PhoneAccountHandle: This value cannot be null.
Return
Conference A Conference which indicates failure. This value cannot be null.

destroy

Added in API level 23
fun destroy(): Unit

Tears down the conference object and any of its current connections.

getCallAudioState

Added in API level 23
Deprecated in API level 34
fun getCallAudioState(): CallAudioState!

Deprecated: Use getCurrentCallEndpoint(), onAvailableCallEndpointsChanged(java.util.List) and onMuteStateChanged(boolean) instead.

Return
CallAudioState! The audio state of the conference, describing how its audio is currently being routed by the system. This is null if this Conference does not directly know about its audio state.

getConferenceableConnections

Added in API level 23
fun getConferenceableConnections(): MutableList<Connection!>!

Returns the connections with which this connection can be conferenced.

getConnectionCapabilities

Added in API level 23
fun getConnectionCapabilities(): Int

Returns the capabilities of the conference. See CAPABILITY_* constants in class Connection for valid values.

Return
Int A bitmask of the capabilities of the conference call.

getConnectionProperties

Added in API level 25
fun getConnectionProperties(): Int

Returns the properties of the conference. See PROPERTY_* constants in class Connection for valid values.

Return
Int A bitmask of the properties of the conference call.

getConnectionStartElapsedRealtimeMillis

Added in API level 30
fun getConnectionStartElapsedRealtimeMillis(): Long

Retrieves the connection start time of the Conference, if specified. A value of CONNECT_TIME_NOT_SPECIFIED indicates that Telecom should determine the start time of the conference.

This is based on the value of SystemClock#elapsedRealtime() to ensure that it is not impacted by wall clock changes (user initiated, network initiated, time zone change, etc).

Note: This is only exposed for use by the Telephony framework which needs it to copy conference start times among conference participants. It is exposed as a system API since it has no general use other than to the Telephony framework.
Value is a non-negative timestamp in the android.os.SystemClock#elapsedRealtime() time base.

Return
Long The elapsed time at which the Conference was connected. Value is a non-negative timestamp in the android.os.SystemClock#elapsedRealtime() time base.

getConnectionTime

Added in API level 23
fun getConnectionTime(): Long

Retrieves the connection start time of the Conference, if specified. A value of CONNECT_TIME_NOT_SPECIFIED indicates that Telecom should determine the start time of the conference.

Return
Long The time at which the Conference was connected. Value is 0 or greater

getConnections

Added in API level 23
fun getConnections(): MutableList<Connection!>!

Returns the list of connections currently associated with the conference call.

Return
MutableList<Connection!>! A list of Connection objects which represent the children of the conference.

getCurrentCallEndpoint

Added in API level 34
fun getCurrentCallEndpoint(): CallEndpoint

Obtains the current CallEndpoint.

Return
CallEndpoint An object encapsulating the CallEndpoint. This value cannot be null.

getDisconnectCause

Added in API level 23
fun getDisconnectCause(): DisconnectCause!
Return
DisconnectCause! The DisconnectCause for this connection.

getExtras

Added in API level 23
fun getExtras(): Bundle!

Returns the extras associated with this conference.

Extras should be updated using putExtras(android.os.Bundle) and removeExtras(java.util.List).

Telecom or an InCallService can also update the extras via android.telecom.Call#putExtras(Bundle), and Call#removeExtras(List).

The conference is notified of changes to the extras made by Telecom or an InCallService by onExtrasChanged(android.os.Bundle).

Return
Bundle! The extras associated with this connection.

getPhoneAccountHandle

Added in API level 23
fun getPhoneAccountHandle(): PhoneAccountHandle!

Returns the PhoneAccountHandle the conference call is being placed through.

Return
PhoneAccountHandle! A PhoneAccountHandle object representing the PhoneAccount of the conference.

getState

Added in API level 23
fun getState(): Int

Gets the state of the conference call. See Connection for valid values.

Return
Int A constant representing the state the conference call is currently in.

getStatusHints

Added in API level 23
fun getStatusHints(): StatusHints!
Return
StatusHints! The status hints for this conference.

getVideoProvider

Added in API level 23
open fun getVideoProvider(): Connection.VideoProvider!

Returns VideoProvider of the primary call. This can be null.

getVideoState

Added in API level 23
open fun getVideoState(): Int

Returns video state of the primary call.

isRingbackRequested

Added in API level 31
fun isRingbackRequested(): Boolean

Returns whether this conference is requesting that the system play a ringback tone on its behalf. A ringback tone may be played when an outgoing conference is in the process of connecting to give the user an audible indication of that process.

onAddConferenceParticipants

Added in API level 31
open fun onAddConferenceParticipants(participants: MutableList<Uri!>): Unit

Notifies the Conference of a request to add a new participants to the conference call

Parameters
participants MutableList<Uri!>: that will be added to this conference call This value cannot be null.

onAnswer

Added in API level 31
open fun onAnswer(videoState: Int): Unit

Notifies this Conference, which is in STATE_RINGING, of a request to accept. For managed ConnectionServices, this will be called when the user answers a call via the default dialer's InCallService.

Parameters
videoState Int: The video state in which to answer the connection. Value is either 0 or a combination of android.telecom.VideoProfile#STATE_AUDIO_ONLY, android.telecom.VideoProfile#STATE_TX_ENABLED, android.telecom.VideoProfile#STATE_RX_ENABLED, android.telecom.VideoProfile#STATE_BIDIRECTIONAL, and android.telecom.VideoProfile#STATE_PAUSED

onAvailableCallEndpointsChanged

Added in API level 34
open fun onAvailableCallEndpointsChanged(availableEndpoints: MutableList<CallEndpoint!>): Unit

Notifies the Conference that the available call endpoints have been changed.

Parameters
availableEndpoints MutableList<CallEndpoint!>: The available call endpoints. This value cannot be null.

onCallAudioStateChanged

Added in API level 23
Deprecated in API level 34
open fun onCallAudioStateChanged(state: CallAudioState!): Unit

Deprecated: Use onCallEndpointChanged(android.telecom.CallEndpoint), onAvailableCallEndpointsChanged(java.util.List) and onMuteStateChanged(boolean) instead.

Notifies the Conference that the getCallAudioState() property has a new value.

Parameters
state CallAudioState!: The new call audio state.

onCallEndpointChanged

Added in API level 34
open fun onCallEndpointChanged(callEndpoint: CallEndpoint): Unit

Notifies the Conference that the audio endpoint has been changed.

Parameters
callEndpoint CallEndpoint: The new call endpoint. This value cannot be null.

onConnectionAdded

Added in API level 23
open fun onConnectionAdded(connection: Connection!): Unit

Notifies the Conference that a Connection has been added to it.

Parameters
connection Connection!: The newly added connection.

onDisconnect

Added in API level 23
open fun onDisconnect(): Unit

Notifies the Conference when the Conference and all it's Connections should be disconnected.

onExtrasChanged

Added in API level 25
open fun onExtrasChanged(extras: Bundle!): Unit

Notifies this Conference of a change to the extras made outside the ConnectionService.

These extras changes can originate from Telecom itself, or from an InCallService via android.telecom.Call#putExtras(Bundle), and Call#removeExtras(List).

Parameters
extras Bundle!: The new extras bundle.

onHold

Added in API level 23
open fun onHold(): Unit

Notifies the Conference when it should be put on hold.

onMerge

Added in API level 23
open fun onMerge(connection: Connection!): Unit

Notifies the Conference when the specified Connection should merged with the conference call.

Parameters
connection Connection!: The Connection to merge.

onMerge

Added in API level 23
open fun onMerge(): Unit

Notifies the Conference when the child calls should be merged. Only invoked if the conference contains the capability Connection#CAPABILITY_MERGE_CONFERENCE.

onMuteStateChanged

Added in API level 34
open fun onMuteStateChanged(isMuted: Boolean): Unit

Notifies the Conference that its audio mute state has been changed.

Parameters
isMuted Boolean: The new mute state.

onPlayDtmfTone

Added in API level 23
open fun onPlayDtmfTone(c: Char): Unit

Notifies the Conference of a request to play a DTMF tone.

Parameters
c Char: A DTMF character.

onReject

Added in API level 31
open fun onReject(): Unit

Notifies this Conference, which is in STATE_RINGING, of a request to reject. For managed ConnectionServices, this will be called when the user rejects a call via the default dialer's InCallService.

onSeparate

Added in API level 23
open fun onSeparate(connection: Connection!): Unit

Notifies the Conference when the specified Connection should be separated from the conference call.

Parameters
connection Connection!: The connection to separate.

onStopDtmfTone

Added in API level 23
open fun onStopDtmfTone(): Unit

Notifies the Conference of a request to stop any currently playing DTMF tones.

onSwap

Added in API level 23
open fun onSwap(): Unit

Notifies the Conference when the child calls should be swapped. Only invoked if the conference contains the capability Connection#CAPABILITY_SWAP_CONFERENCE.

onUnhold

Added in API level 23
open fun onUnhold(): Unit

Notifies the Conference when it should be moved from a held to active state.

putExtras

Added in API level 25
fun putExtras(extras: Bundle): Unit

Adds some extras to this Conference. 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.

Parameters
extras Bundle: The extras to add. This value cannot be null.

removeConnection

Added in API level 23
fun removeConnection(connection: Connection!): Unit

Removes the specified connection as a child of this conference.

Parameters
connection Connection!: The connection to remove.

removeExtras

Added in API level 25
fun removeExtras(keys: MutableList<String!>!): Unit

Removes extras from this Conference.

Parameters
keys MutableList<String!>!: The keys of the extras to remove.

removeExtras

Added in API level 25
fun removeExtras(vararg keys: String!): Unit

Removes extras from this Conference.

Parameters
keys String!: The keys of the extras to remove.

sendConferenceEvent

Added in API level 30
open fun sendConferenceEvent(
    event: String,
    extras: Bundle?
): Unit

Sends an event associated with this Conference with associated event extras to the InCallService.

Connection events are used to communicate point in time information from a ConnectionService to an InCallService implementation. 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 Connection#EVENT_MERGE_COMPLETE connection event when a call to Call#mergeConference() has completed successfully.

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.

Expected connection events from the Telephony stack are:

Parameters
event String: The conference event. This value cannot be null.
extras Bundle?: Optional bundle containing extra information associated with the event. This value may be null.

setActive

Added in API level 23
fun setActive(): Unit

Sets state to be active.

setConferenceableConnections

Added in API level 23
fun setConferenceableConnections(conferenceableConnections: MutableList<Connection!>!): Unit

Sets the connections with which this connection can be conferenced.

Parameters
conferenceableConnections MutableList<Connection!>!: The set of connections this connection can conference with.

setConnectionCapabilities

Added in API level 23
fun setConnectionCapabilities(connectionCapabilities: Int): Unit

Sets the capabilities of a conference. See CAPABILITY_* constants of class Connection for valid values.

Parameters
connectionCapabilities Int: A bitmask of the Capabilities of the conference call.

setConnectionProperties

Added in API level 25
fun setConnectionProperties(connectionProperties: Int): Unit

Sets the properties of a conference. See PROPERTY_* constants of class Connection for valid values.

Parameters
connectionProperties Int: A bitmask of the Properties of the conference call.

setConnectionStartElapsedRealTime

Added in API level 28
Deprecated in API level 30
fun setConnectionStartElapsedRealTime(connectionStartElapsedRealTime: Long): Unit

Deprecated: use setConnectionStartElapsedRealtimeMillis(long) instead.

Sets the start time of the Conference which is the basis for the determining the duration of the Conference.

You should use a value returned by SystemClock#elapsedRealtime() to ensure that time zone changes do not impact the conference duration.

When setting this, you should also set the connection time via setConnectionTime(long).

Parameters
connectionStartElapsedRealTime Long: The connection time, as measured by SystemClock#elapsedRealtime().

setConnectionStartElapsedRealtimeMillis

Added in API level 30
fun setConnectionStartElapsedRealtimeMillis(connectionStartElapsedRealTime: Long): Unit

Sets the start time of the Conference which is the basis for the determining the duration of the Conference.

You should use a value returned by SystemClock#elapsedRealtime() to ensure that time zone changes do not impact the conference duration.

When setting this, you should also set the connection time via setConnectionTime(long).

Parameters
connectionStartElapsedRealTime Long: The connection time, as measured by SystemClock#elapsedRealtime(). Value is a non-negative timestamp in the android.os.SystemClock#elapsedRealtime() time base.

setConnectionTime

Added in API level 23
fun setConnectionTime(connectionTimeMillis: Long): Unit

Sets the connection start time of the Conference. This is used in the call log to indicate the date and time when the conference took place.

Should be specified in wall-clock time returned by System#currentTimeMillis().

When setting the connection time, you should always set the connection elapsed time via setConnectionStartElapsedRealtimeMillis(long) to ensure the duration is reflected.

Parameters
connectionTimeMillis Long: The connection time, in milliseconds, as returned by System#currentTimeMillis(). Value is 0 or greater

setDialing

Added in API level 23
fun setDialing(): Unit

Sets state to be dialing.

setDisconnected

Added in API level 23
fun setDisconnected(disconnectCause: DisconnectCause!): Unit

Sets state to disconnected.

Parameters
disconnectCause DisconnectCause!: The reason for the disconnection, as described by android.telecom.DisconnectCause.

setExtras

Added in API level 23
fun setExtras(extras: Bundle?): Unit

Replaces all the extras associated with this Conference.

New or existing keys are replaced in the Conference 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(android.os.Bundle), and removeExtras(java.lang.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.extras.MY_EXTRA) to avoid conflicts.

Parameters
extras Bundle?: The extras associated with this Conference. This value may be null.

setOnHold

Added in API level 23
fun setOnHold(): Unit

Sets state to be on hold.

setRingbackRequested

Added in API level 31
fun setRingbackRequested(ringback: Boolean): Unit

Requests that the framework play a ringback tone. This is to be invoked by implementations that do not play a ringback tone themselves in the conference's audio stream.

Parameters
ringback Boolean: Whether the ringback tone is to be played.

setRinging

Added in API level 31
fun setRinging(): Unit

Sets state to be ringing.

setStatusHints

Added in API level 23
fun setStatusHints(statusHints: StatusHints!): Unit

Sets the label and icon status to display in the InCall UI.

Parameters
statusHints StatusHints!: The status label and icon to set.

setVideoProvider

Added in API level 23
fun setVideoProvider(
    c: Connection!,
    videoProvider: Connection.VideoProvider!
): Unit

Sets the video connection provider.

Parameters
videoProvider Connection.VideoProvider!: The video provider.

setVideoState

Added in API level 23
fun setVideoState(
    c: Connection!,
    videoState: Int
): Unit

Set the video state for the conference. Valid values: VideoProfile#STATE_AUDIO_ONLY, VideoProfile#STATE_BIDIRECTIONAL, VideoProfile#STATE_TX_ENABLED, VideoProfile#STATE_RX_ENABLED.

Parameters
videoState Int: The new video state.

toString

Added in API level 23
open fun toString(): String
Return
String a string representation of the object.