CallControlScope


interface CallControlScope : CoroutineScope


DSL interface to provide and receive updates about a call session. The CallControlScope should be used to provide updates (via the CallControlScope suspend functions) and receive updates (via the lambda functions) about the call. The CallControlScope will run for the duration of the call. To see an example implementation of the CallControlScope, please refer to the sample app on github.

Example usage:

// initiate a call and control via the CallControlScope
mCallsManager.addCall(
    callAttributes,
    onAnswerLambda,
    onDisconnectLambda,
    onSetActiveLambda,
    onSetInActiveLambda
    ) {
    // This block represents the CallControlScope. Once Telecom has added the call to the
    // system, your application can start changing the call state (via setActive(), etc.),
    // collect the flows.


      // Your application should gate ALL CallControlScope suspend functions with UI logic or
      // logic that signals the call state is ready to be changed
      launch {
             when (val res = setActive() ) {

               is CallControlResult.Success -> {
                 // Telecom can place the active
                 // update your call state and handle UI
               }

               is CallControlResult.Error -> {
                 // Telecom cannot set your VoIP call active. Maybe there is an ongoing
                 // active call that cannot be held. Check the failure code to determine the
                 // recommended next action
                 handleErrorCode( res.errorCode )
               }
              }
            }
       }

      // Collect updates
      launch {
         currentCallEndpoint.collect { // access the new [CallEndpoint] here }
      }

      launch {
         availableEndpoints.collect { // access the available [CallEndpoint]s here }
      }

      launch {
         isMuted.collect { // access to the mute state }
      }
  }

Note: Each Flow must be wrapped in an individual launch block or the Flow will not be collected.

Summary

Public functions

suspend CallControlResult
answer(callType: Int)

Inform Telecom that your app wants to make this incoming call active.

suspend CallControlResult
disconnect(disconnectCause: DisconnectCause)

Inform Telecom that your app wishes to disconnect the call and remove the call from telecom tracking.

ParcelUuid
suspend CallControlResult

Request a CallEndpointCompat change.

suspend CallControlResult

Inform Telecom that your app wants to make this call active.

suspend CallControlResult

Inform Telecom that your app wants to make this call inactive.

Public properties

Flow<List<CallEndpointCompat>>

Collect the set of available CallEndpointCompats reported by Telecom.

Flow<CallEndpointCompat>

Collect the new CallEndpointCompat through which call media flows (i.e. speaker, bluetooth, etc.).

Flow<Boolean>

Collect the current mute state of the call.

Public functions

answer

suspend fun answer(callType: Int): CallControlResult

Inform Telecom that your app wants to make this incoming call active. For outgoing calls and calls that have been placed on hold, use setActive.

Parameters
callType: Int

that call is to be answered as.

Returns
CallControlResult

Telecom will return CallControlResult.Success if your app is able to answer the call. Otherwise CallControlResult.Error will be returned with an error code indicating why answer failed (ex. another call is active and telecom cannot set this call active until the other call is held or disconnected). This means that your app cannot answer this call at this time.

disconnect

suspend fun disconnect(disconnectCause: DisconnectCause): CallControlResult

Inform Telecom that your app wishes to 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:

  • DisconnectCause#LOCAL
  • DisconnectCause#REMOTE
  • DisconnectCause#REJECTED
  • DisconnectCause#MISSED

Returns
CallControlResult

CallControlResult.Success will be returned if Telecom is able to disconnect the call successfully. Otherwise CallControlResult.Error will be returned with an error code indicating why disconnect failed.

getCallId

Added in 1.0.0-alpha03
fun getCallId(): ParcelUuid
Returns
ParcelUuid

the 128-bit universally unique identifier Telecom assigned to this CallControlScope. This id can be helpful for debugging when dumping the telecom system.

requestEndpointChange

suspend fun requestEndpointChange(endpoint: CallEndpointCompat): CallControlResult

Request a CallEndpointCompat change. Clients should not define their own CallEndpointCompat when requesting a change. Instead, the new endpoint should be one of the valid CallEndpointCompats provided by availableEndpoints.

Parameters
endpoint: CallEndpointCompat

The CallEndpointCompat to change to.

Returns
CallControlResult

CallControlResult.Success will be returned if Telecom is able to switch to the requested endpoint successfully. Otherwise, CallControlResult.Error will be returned with an error code indicating why disconnect failed.

setActive

suspend fun setActive(): CallControlResult

Inform Telecom that your app wants to make this call 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 answer.

Returns
CallControlResult

Telecom will return CallControlResult.Success if your app is able to set the call active. Otherwise CallControlResult.Error will be returned (ex. another call is active and telecom cannot set this call active until the other call is held or disconnected) with an error code indicating why setActive failed.

setInactive

suspend fun setInactive(): CallControlResult

Inform Telecom that your app wants to make this call inactive. This the same as hold for two call endpoints but can be extended to setting a meeting to inactive.

Returns
CallControlResult

Telecom will return CallControlResult.Success if your app is able to set the call inactive. Otherwise, CallControlResult.Error will be returned with an error code indicating why setInActive failed.

Public properties

availableEndpoints

Added in 1.0.0-alpha03
val availableEndpointsFlow<List<CallEndpointCompat>>

Collect the set of available CallEndpointCompats reported by Telecom.

currentCallEndpoint

Added in 1.0.0-alpha03
val currentCallEndpointFlow<CallEndpointCompat>

Collect the new CallEndpointCompat through which call media flows (i.e. speaker, bluetooth, etc.).

isMuted

Added in 1.0.0-alpha03
val isMutedFlow<Boolean>

Collect the current mute state of the call. This Flow is updated every time the mute state changes.