Added in API level 34

CallControl

class CallControl
kotlin.Any
   ↳ android.telecom.CallControl

CallControl provides client side control of a call. Each Call will get an individual CallControl instance in which the client can alter the state of the associated call. Outgoing and incoming calls should move to active (via CallControl.setActive(Executor, OutcomeReceiver) or answered (via CallControl.answer(int, Executor, OutcomeReceiver) before 60 seconds. If the new call is not moved to active or answered before 60 seconds, the call will be disconnected.

Each method is Transactional meaning that it can succeed or fail. If a transaction succeeds, the OutcomeReceiver.onResult will be called by Telecom. Otherwise, the OutcomeReceiver.onError is called and provides a CallException that details why the operation failed.

Summary

Public methods
Unit
answer(callType: Int, executor: Executor, callback: OutcomeReceiver<Void!, CallException!>)

Request Telecom answer an incoming call.
Unit
disconnect(disconnectCause: DisconnectCause, executor: Executor, callback: OutcomeReceiver<Void!, CallException!>)

Request Telecom disconnect the call and remove the call from telecom tracking.
ParcelUuid

Unit

Request a CallEndpoint change.
Unit
requestMuteState(isMuted: Boolean, executor: Executor, callback: OutcomeReceiver<Void!, CallException!>)

Request a new mute state.
Unit
requestVideoState(callType: Int, executor: Executor, callback: OutcomeReceiver<Void!, CallException!>)

Request a new video state for the ongoing call.
Unit
sendEvent(event: String, extras: Bundle)

Raises an event to the android.telecom.InCallService implementations tracking this call via android.telecom.Call.Callback#onConnectionEvent(Call, String, Bundle).
Unit
setActive(executor: Executor, callback: OutcomeReceiver<Void!, CallException!>)

Request Telecom set the call state to active.
Unit
setContactUri(uri: Uri?, executor: Executor, callback: OutcomeReceiver<Void!, CallException!>)

Sets the VoIP contact URI for an ongoing call.
Unit
setGroupCallState(isGroupCall: Boolean, executor: Executor, callback: OutcomeReceiver<Void!, CallException!>)

Sets the group call state for an ongoing call.
Unit

Request Telecom set the call state to inactive.
Unit

Request start a call streaming session.

Public methods

answer

Added in API level 34
fun answer(
    callType: Int, 
    executor: Executor, 
    callback: OutcomeReceiver<Void!, CallException!>
): Unit

Request Telecom answer an incoming call. For outgoing calls and calls that have been placed on hold, use CallControl.setActive(Executor, OutcomeReceiver).

Parameters
callType Int: to report to Telecom. Telecom will store CallType in the event another service/device requests it in order to continue the call on another screen.
Value is one of the following:
executor Executor: The Executor on which the OutcomeReceiver callback will be called on.
Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
This value cannot be null.
callback OutcomeReceiver<Void!, CallException!>: that will be completed on the Telecom side that details success or failure of the requested operation. OutcomeReceiver.onResult will be called if Telecom has successfully switched the call state to active OutcomeReceiver.onError will be called if Telecom has failed to set the call state to active. A CallException will be passed that details why the operation failed.
This value cannot be null.

disconnect

Added in API level 34
fun disconnect(
    disconnectCause: DisconnectCause, 
    executor: Executor, 
    callback: OutcomeReceiver<Void!, CallException!>
): Unit

Request Telecom disconnect the call and remove the call from telecom tracking.

Parameters
disconnectCause DisconnectCause: represents the cause for disconnecting the call. The only valid codes for the android.telecom.DisconnectCause passed in are: .
This value cannot be null.
executor Executor: The Executor on which the OutcomeReceiver callback will be called on.
Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
This value cannot be null.
callback OutcomeReceiver<Void!, CallException!>: That will be completed on the Telecom side that details success or failure of the requested operation. OutcomeReceiver.onResult will be called if Telecom has successfully disconnected the call. OutcomeReceiver.onError will be called if Telecom has failed to disconnect the call. A CallException will be passed that details why the operation failed.

Note: After the call has been successfully disconnected, calling any CallControl API will result in the OutcomeReceiver.onError with CallException.CODE_CALL_IS_NOT_BEING_TRACKED.
This value cannot be null.

getCallId

Added in API level 34
fun getCallId(): ParcelUuid
Return
ParcelUuid the callId Telecom assigned to this CallControl object which should be attached to an individual call.
This value cannot be null.

requestCallEndpointChange

Added in API level 34
fun requestCallEndpointChange(
    callEndpoint: CallEndpoint, 
    executor: Executor, 
    callback: OutcomeReceiver<Void!, CallException!>
): Unit

Request a CallEndpoint change. Clients should not define their own CallEndpoint when requesting a change. Instead, the new endpoint should be one of the valid endpoints provided by CallEventCallback.onAvailableCallEndpointsChanged(List).

Parameters
callEndpoint CallEndpoint: The CallEndpoint to change to.
This value cannot be null.
executor Executor: The Executor on which the OutcomeReceiver callback will be called on.
Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
This value cannot be null.
callback OutcomeReceiver<Void!, CallException!>: The OutcomeReceiver that will be completed on the Telecom side that details success or failure of the requested operation. OutcomeReceiver.onResult will be called if Telecom has successfully changed the CallEndpoint that was requested. OutcomeReceiver.onError will be called if Telecom has failed to switch to the requested CallEndpoint. A CallException will be passed that details why the operation failed.
This value cannot be null.

requestMuteState

Added in API level 35
fun requestMuteState(
    isMuted: Boolean, 
    executor: Executor, 
    callback: OutcomeReceiver<Void!, CallException!>
): Unit

Request a new mute state. Note: CallEventCallback.onMuteStateChanged(boolean) will be called every time the mute state is changed and can be used to track the current mute state.

Parameters
isMuted Boolean: The new mute state. Passing in a Boolean.TRUE for the isMuted parameter will mute the call. Boolean.FALSE will unmute the call.
executor Executor: The Executor on which the OutcomeReceiver callback will be called on.
Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
This value cannot be null.
callback OutcomeReceiver<Void!, CallException!>: The OutcomeReceiver that will be completed on the Telecom side that details success or failure of the requested operation. OutcomeReceiver.onResult will be called if Telecom has successfully changed the mute state. OutcomeReceiver.onError will be called if Telecom has failed to switch to the mute state. A CallException will be passed that details why the operation failed.
This value cannot be null.

requestVideoState

Added in API level 35
fun requestVideoState(
    callType: Int, 
    executor: Executor, 
    callback: OutcomeReceiver<Void!, CallException!>
): Unit

Request a new video state for the ongoing call. This can only be changed if the application has registered a PhoneAccount with the PhoneAccount.CAPABILITY_SUPPORTS_VIDEO_CALLING and set the CallAttributes.SUPPORTS_VIDEO_CALLING when adding the call via TelecomManager.addCall(CallAttributes, Executor, OutcomeReceiver, CallControlCallback, CallEventCallback)

Parameters
callType Int: to report to Telecom. To see the valid argument to pass, see android.telecom.CallAttributes.CallType.
Value is one of the following:
executor Executor: The Executor on which the OutcomeReceiver callback will be called on.
Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
This value cannot be null.
callback OutcomeReceiver<Void!, CallException!>: that will be completed on the Telecom side that details success or failure of the requested operation. OutcomeReceiver.onResult will be called if Telecom has successfully switched the video state. OutcomeReceiver.onError will be called if Telecom has failed to set the new video state. A CallException will be passed that details why the operation failed.
This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if the argument passed for videoState is invalid. To see a list of valid states, see android.telecom.CallAttributes.CallType.

sendEvent

Added in API level 34
fun sendEvent(
    event: String, 
    extras: Bundle
): Unit

Raises an event to the android.telecom.InCallService implementations tracking this call via android.telecom.Call.Callback#onConnectionEvent(Call, String, Bundle). These events and the associated extra keys for the Bundle parameter are mutually defined by a VoIP application and android.telecom.InCallService. This API is used to relay additional information about a call other than what is specified in the android.telecom.CallAttributes to android.telecom.InCallServices. This might include, for example, a change to the list of participants in a meeting, or the name of the speakers who have their hand raised. Where appropriate, the InCallServices tracking this call may choose to render this additional information about the call. An automotive calling UX, for example may have enough screen real estate to indicate the number of participants in a meeting, but to prevent distractions could suppress the list of participants.

Parameters
event String: a string event identifier agreed upon between a VoIP application and an android.telecom.InCallService
This value cannot be null.
extras Bundle: a android.os.Bundle containing information about the event, as agreed upon between a VoIP application and android.telecom.InCallService.
This value cannot be null.

setActive

Added in API level 34
fun setActive(
    executor: Executor, 
    callback: OutcomeReceiver<Void!, CallException!>
): Unit

Request Telecom set the call state to active. This method should be called when either an outgoing call is ready to go active or a held call is ready to go active again. For incoming calls that are ready to be answered, use CallControl.answer(int, Executor, OutcomeReceiver).

Parameters
executor Executor: The Executor on which the OutcomeReceiver callback will be called on.
Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
This value cannot be null.
callback OutcomeReceiver<Void!, CallException!>: that will be completed on the Telecom side that details success or failure of the requested operation. OutcomeReceiver.onResult will be called if Telecom has successfully switched the call state to active OutcomeReceiver.onError will be called if Telecom has failed to set the call state to active. A CallException will be passed that details why the operation failed.
This value cannot be null.

setContactUri

Added in API level 34
fun setContactUri(
    uri: Uri?, 
    executor: Executor, 
    callback: OutcomeReceiver<Void!, CallException!>
): Unit

Sets the VoIP contact URI for an ongoing call.

This method should be invoked by a VoIP application. when a call transitions to or from being a group call. For instance, if a one-on-one call adds more participants and becomes a conference. This should be used in par with CallControl.setGroupCallState.

Providing this state allows the Android system to correctly represent the call in the system's user interface, such as the native call log. As part of the integrated call logs feature, which provides a unified history for both carrier and VoIP calls, accurately associating the calls with a valid lookup URI is essential for a consistent user experience.

The uri parameter is crucial for linking the call to a specific group entity within the VoIP contact directory or a CP2 contact. This helps in associating the call log entry with the correct contact information, such as the group's name and avatar.

Parameters
uri Uri?: The content URI of the contact or group in the VoIP application's contact directory or a valid CP2 contact. This URI must be stable and resolvable by the system or null if unused.
executor Executor: The Executor on which the OutcomeReceiver callback will be called on.
Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
This value cannot be null.
callback OutcomeReceiver<Void!, CallException!>: that will be completed on the Telecom side that details success or failure of the requested operation. OutcomeReceiver.onResult will be called if Telecom has successfully switched the video state. OutcomeReceiver.onError will be called if Telecom has failed to set the new video state. A CallException will be passed that details why the operation failed.
This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if the provided uri is invalid or improperly formatted.

setGroupCallState

Added in API level 34
fun setGroupCallState(
    isGroupCall: Boolean, 
    executor: Executor, 
    callback: OutcomeReceiver<Void!, CallException!>
): Unit

Sets the group call state for an ongoing call.

This method should be invoked by a VoIP application. when a call transitions to or from being a group call. For instance, if a one-on-one call adds more participants and becomes a conference, this method informs the system of that change.

Providing this state allows the Android system to correctly represent the call in the system's user interface, such as the native call log. As part of the integrated call logs feature, which provides a unified history for both carrier and VoIP calls, accurately identifying group calls is essential for a consistent user experience.

Parameters
isGroupCall Boolean: true if the call is currently a group call, false otherwise.
executor Executor: The Executor on which the OutcomeReceiver callback will be called on.
Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
This value cannot be null.
callback OutcomeReceiver<Void!, CallException!>: that will be completed on the Telecom side that details success or failure of the requested operation. OutcomeReceiver.onResult will be called if Telecom has successfully switched the video state. OutcomeReceiver.onError will be called if Telecom has failed to set the new video state. A CallException will be passed that details why the operation failed.
This value cannot be null.

setInactive

Added in API level 34
fun setInactive(
    executor: Executor, 
    callback: OutcomeReceiver<Void!, CallException!>
): Unit

Request Telecom set the call state to inactive. This the same as hold for two call endpoints but can be extended to setting a meeting to inactive.

Parameters
executor Executor: The Executor on which the OutcomeReceiver callback will be called on.
Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
This value cannot be null.
callback OutcomeReceiver<Void!, CallException!>: that will be completed on the Telecom side that details success or failure of the requested operation. OutcomeReceiver.onResult will be called if Telecom has successfully switched the call state to inactive OutcomeReceiver.onError will be called if Telecom has failed to set the call state to inactive. A CallException will be passed that details why the operation failed.
This value cannot be null.

startCallStreaming

Added in API level 34
fun startCallStreaming(
    executor: Executor, 
    callback: OutcomeReceiver<Void!, CallException!>
): Unit

Request start a call streaming session. On receiving valid request, telecom will bind to the CallStreamingService implemented by a general call streaming sender. So that the call streaming sender can perform streaming local device audio to another remote device and control the call during streaming.

Parameters
executor Executor: The Executor on which the OutcomeReceiver callback will be called on.
Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
This value cannot be null.
callback OutcomeReceiver<Void!, CallException!>: that will be completed on the Telecom side that details success or failure of the requested operation. OutcomeReceiver.onResult will be called if Telecom has successfully started the call streaming. OutcomeReceiver.onError will be called if Telecom has failed to start the call streaming. A CallException will be passed that details why the operation failed.
This value cannot be null.