CallsManager

const val CAPABILITY_BASELINE: Int

If your VoIP application does not want support any of the capabilities below, then your application can register with CAPABILITY_BASELINE.

Note: Calls can still be added and to the Telecom system but if other services request to perform a capability that is not supported by your application, Telecom will notify the service of the inability to perform the action instead of hitting an error.

const val CAPABILITY_SUPPORTS_CALL_STREAMING: Int

Flag indicating that this VoIP application supports call streaming. Call streaming means a call can be streamed from a root device to another device to continue the call without completely transferring it. The call continues to take place on the source device, however media and control are streamed to another device. androidx.core.telecom.CallAttributesCompat.CallType#CAPABILITY_SUPPORTS_CALL_STREAMING must also be set on per call basis in the event an application wants to gate this capability on a stricter basis.

const val CAPABILITY_SUPPORTS_VIDEO_CALLING: Int

Flag indicating that your VoIP application supports video calling. This is not an indication that your application is currently able to make a video call, but rather that it has the ability to make video calls (but not necessarily at this time).

Whether a call can make a video call is ultimately controlled by androidx.core.telecom.CallAttributesCompats capability androidx.core.telecom.CallAttributesCompat.CallType#CALL_TYPE_VIDEO_CALL, which indicates that particular call is currently capable of making a video call.

@RequiresPermission(value = "android.permission.MANAGE_OWN_CALLS")
suspend fun addCall(
    callAttributes: CallAttributesCompat,
    onAnswer: suspend (callType: Int) -> Unit,
    onDisconnect: suspend (disconnectCause: DisconnectCause) -> Unit,
    onSetActive: suspend () -> Unit,
    onSetInactive: suspend () -> Unit,
    block: CallControlScope.() -> Unit
): Unit

Adds a new call with the specified CallAttributesCompat to the telecom service. This method can be used to add both incoming and outgoing calls. Once the call is ready to be disconnected, use the CallControlScope.disconnect.

Call Lifecycle: Your app is given foreground execution priority as long as you have an ongoing call and are posting a android.app.Notification.CallStyle notification within 5 seconds of adding the call via this method. When your application is given foreground execution priority, your app is treated as a foreground service. Foreground execution priority will prevent the android.app.ActivityManager from killing your application when it is placed the background. Foreground execution priority is removed from your app when all of your app's calls terminate or your app no longer posts a valid notification.

• Other things that should be noted:

• For outgoing calls, your application should either immediately post a android.app.Notification.CallStyle notification or delay adding the call via this addCall method until the remote side is ready.

• addCall will NOT complete until the call session has ended. Instead, the addCall block, which is called the CallControlScope, will run once the call has been added. Do not put addCall in a function expecting it to return or add logic after the addCall request that is important for the call session.

• Each lambda function (onAnswer, onDisconnect, onSetActive, onSetInactive) will be invoked by Telecom whenever the system needs your VoIP application to change the call state. For example, if there is an ongoing VoIP call in your application and the system receives a sim call, Telecom will invoke onSetInactive to place your call on hold/inactive if the user answers the incoming sim call. These events may not occur during most calls but should still be implemented in the event Telecom needs to manipulate your applications call state.

• Each lambda function (onAnswer, onDisconnect, onSetActive, onSetInactive) has a timeout of 5000 milliseconds. Failing to complete the suspend fun before the timeout will result in a failed transaction.

• Telecom assumes each callback (onAnswer, onDisconnect, onSetActive, onSetInactive) is handled successfully on the client side. If the callback cannot be completed, an Exception should be thrown. Telecom will rethrow the Exception and tear down the call session.

@ExperimentalAppActions
open suspend fun addCallWithExtensions(
    callAttributes: CallAttributesCompat,
    onAnswer: suspend (callType: Int) -> Unit,
    onDisconnect: suspend (disconnectCause: DisconnectCause) -> Unit,
    onSetActive: suspend () -> Unit,
    onSetInactive: suspend () -> Unit,
    init: suspend ExtensionInitializationScope.() -> Unit
): Unit

Adds a call with extensions support, which allows an app to implement optional additional actions that go beyond the scope of a call, such as information about meeting participants and icons.

fun getAvailableStartingCallEndpoints(): Flow<List<CallEndpointCompat>>

Continuously stream the available call audio endpoints that can be used for a new call session. The callbackFlow should be cleaned up client-side by calling cancel() from the same kotlinx.coroutines.CoroutineScope the callbackFlow is collecting in.

Note: The endpoints emitted will be sorted by the CallEndpointCompat.type . See CallEndpointCompat.compareTo for the ordering. The first element in the list will be the recommended call endpoint to default to for the user.

@RequiresPermission(value = "android.permission.MANAGE_OWN_CALLS")
fun registerAppWithTelecom(capabilities: Int): Unit

VoIP applications should look at each Capability annotated above and call this API in order to start adding calls via addCall. Registering capabilities must be done before calling addCall or an exception will be thrown by addCall. The capabilities can be updated by re-registering.

Note: There is no need to unregister at any point. Telecom will handle unregistering once the application using core-telecom has been removed from the device.