CallControlScope

Added in 1.0.0

Kotlin |Java

public interface CallControlScope extends 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 methods
`abstract @NonNull CallControlResult`	`answer(int callType)` Inform Telecom that your app wants to make this incoming call active.
`default @NonNull Flow<@NonNull Integer>`	`callTypeFlow()` Returns a `Flow` that emits the current call type state and subsequent updates.
`abstract @NonNull CallControlResult`	`disconnect(@NonNull DisconnectCause disconnectCause)` Inform Telecom that your app wishes to disconnect the call and remove the call from telecom tracking.
`abstract @NonNull Flow<@NonNull List<@NonNull CallEndpointCompat>>`	`getAvailableEndpoints()` Collect the set of available `CallEndpointCompat`s reported by Telecom.
`abstract @NonNull ParcelUuid`	`getCallId()`
`abstract @NonNull Flow<@NonNull CallEndpointCompat>`	`getCurrentCallEndpoint()` Collect the new `CallEndpointCompat` through which call media flows (i.e. speaker, bluetooth, etc.).
`abstract @NonNull Flow<@NonNull Boolean>`	`isMuted()` Collect the current mute state of the call.
`default @NonNull CallControlResult`	`requestCallType(int callType)` Requests a change to the call type for the current call.
`abstract @NonNull CallControlResult`	`requestEndpointChange(@NonNull CallEndpointCompat endpoint)` Request a `CallEndpointCompat` change.
`abstract @NonNull CallControlResult`	`setActive()` Inform Telecom that your app wants to make this call active.
`abstract @NonNull CallControlResult`	`setInactive()` Inform Telecom that your app wants to make this call inactive.

Inherited methods

From kotlinx.coroutines.CoroutineScope

abstract @NonNull CoroutineContext

getCoroutineContext()

Public methods

answer

abstract @NonNull CallControlResult answer(int callType)

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
`int callType`	that call is to be answered as.

Returns
`@NonNull 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.

callTypeFlow

Added in 1.1.0-alpha02

default @NonNull Flow<@NonNull Integer> callTypeFlow()

Returns a Flow that emits the current call type state and subsequent updates.

The emitted values are integers corresponding to the constants defined in CallAttributesCompat.Companion.CallType, such as CallAttributesCompat.CALL_TYPE_AUDIO_CALL or CallAttributesCompat.CALL_TYPE_VIDEO_CALL.

Upon collection, the Flow will emit the current call type state immediately, and then emit new values whenever the call type changes (e.g., from audio to video). This is a cold Flow; emissions start only when the Flow is collected.

Returns
`@NonNull Flow<@NonNull Integer>`	A `Flow` of `Int` representing the current call type state. Collectors will receive the latest state and any changes thereafter.

disconnect

abstract @NonNull CallControlResult disconnect(@NonNull DisconnectCause disconnectCause)

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

Parameters

Parameters
`@NonNull 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

@NonNull 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
`@NonNull 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.

getAvailableEndpoints

Added in 1.0.0

abstract @NonNull Flow<@NonNull List<@NonNull CallEndpointCompat>> getAvailableEndpoints()

Collect the set of available CallEndpointCompats reported by Telecom.

getCallId

Added in 1.0.0

abstract @NonNull ParcelUuid getCallId()

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

getCurrentCallEndpoint

Added in 1.0.0

abstract @NonNull Flow<@NonNull CallEndpointCompat> getCurrentCallEndpoint()

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

isMuted

Added in 1.0.0

abstract @NonNull Flow<@NonNull Boolean> isMuted()

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

requestCallType

default @NonNull CallControlResult requestCallType(int callType)

Requests a change to the call type for the current call.

Use this method to transition the call between different states, for example, to upgrade an audio-only call to a video call, or downgrade a video call to audio-only.

Parameters
`int callType`	The desired call type for the call. This must be one of the integer constants defined in `CallAttributesCompat.Companion.CallType`, such as `CallAttributesCompat.CALL_TYPE_AUDIO_CALL` or `CallAttributesCompat.CALL_TYPE_VIDEO_CALL`.

Returns
`@NonNull CallControlResult`	A `CallControlResult` indicating the outcome of the request: - `CallControlResult.Success`: The request to change the call type was successfully processed by the Telecom framework. - `CallControlResult.Error`: The request failed. The specific reason for the failure can be determined by the error code within the `CallControlResult.Error`

requestEndpointChange

abstract @NonNull CallControlResult requestEndpointChange(@NonNull CallEndpointCompat endpoint)

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
`@NonNull CallEndpointCompat endpoint`	The `CallEndpointCompat` to change to.

Returns
`@NonNull 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

abstract @NonNull CallControlResult setActive()

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
`@NonNull 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

abstract @NonNull CallControlResult setInactive()

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
`@NonNull 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.