CallsManager


@RequiresApi(value = 26)
public final class CallsManager


CallsManager allows VoIP applications to add their calls to the Android system service Telecom. By doing this, other services are aware of your VoIP application calls which leads to a more stable environment. For example, a wearable may be able to answer an incoming call from your application if the call is added to the Telecom system. VoIP applications that manage calls and do not inform the Telecom system may experience issues with resources (ex. microphone access).

Note that access to some telecom information is permission-protected. Your app cannot access the protected information or gain access to protected functionality unless it has the appropriate permissions declared in its manifest file. Where permissions apply, they are noted in the method descriptions.

Summary

Constants

static final int

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

static final int

Flag indicating that this VoIP application supports call streaming.

static final int

Flag indicating that your VoIP application supports video calling.

Public constructors

Public methods

final void
@RequiresPermission(value = "android.permission.MANAGE_OWN_CALLS")
addCall(
    @NonNull CallAttributesCompat callAttributes,
    @NonNull SuspendFunction1<@NonNull IntegerUnit> onAnswer,
    @NonNull SuspendFunction1<@NonNull DisconnectCauseUnit> onDisconnect,
    @NonNull SuspendFunction0<Unit> onSetActive,
    @NonNull SuspendFunction0<Unit> onSetInactive,
    @ExtensionFunctionType @NonNull Function1<@NonNull CallControlScopeUnit> block
)

Adds a new call with the specified CallAttributesCompat to the telecom service.

final void
@RequiresPermission(value = "android.permission.MANAGE_OWN_CALLS")
registerAppWithTelecom(int capabilities)

VoIP applications should look at each Capability annotated above and call this API in order to start adding calls via addCall.

Constants

CAPABILITY_BASELINE

public static final int CAPABILITY_BASELINE

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.

CAPABILITY_SUPPORTS_CALL_STREAMING

public static final int CAPABILITY_SUPPORTS_CALL_STREAMING

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.

CAPABILITY_SUPPORTS_VIDEO_CALLING

public static final int CAPABILITY_SUPPORTS_VIDEO_CALLING

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.

Public constructors

CallsManager

Added in 1.0.0-alpha03
public CallsManager(@NonNull Context context)

Public methods

addCall

Added in 1.0.0-alpha03
@RequiresPermission(value = "android.permission.MANAGE_OWN_CALLS")
public final void addCall(
    @NonNull CallAttributesCompat callAttributes,
    @NonNull SuspendFunction1<@NonNull IntegerUnit> onAnswer,
    @NonNull SuspendFunction1<@NonNull DisconnectCauseUnit> onDisconnect,
    @NonNull SuspendFunction0<Unit> onSetActive,
    @NonNull SuspendFunction0<Unit> onSetInactive,
    @ExtensionFunctionType @NonNull Function1<@NonNull CallControlScopeUnit> block
)

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.

Parameters
@NonNull CallAttributesCompat callAttributes

attributes of the new call (incoming or outgoing, address, etc. )

@NonNull SuspendFunction1<@NonNull IntegerUnit> onAnswer

where callType is the audio/video state the call should be answered as. Telecom is informing your VoIP application to answer an incoming call and set it to active. Telecom is requesting this on behalf of an system service (e.g. Automotive service) or a device (e.g. Wearable).

@NonNull SuspendFunction1<@NonNull DisconnectCauseUnit> onDisconnect

where disconnectCause represents the cause for disconnecting the call. Telecom is informing your VoIP application to disconnect the incoming call. Telecom is requesting this on behalf of an system service (e.g. Automotive service) or a device (e.g. Wearable).

@NonNull SuspendFunction0<Unit> onSetActive

Telecom is informing your VoIP application to set the call active. Telecom is requesting this on behalf of an system service (e.g. Automotive service) or a device (e.g. Wearable).

@NonNull SuspendFunction0<Unit> onSetInactive

Telecom is informing your VoIP application to set the call inactive. This is the same as holding a call for two endpoints but can be extended to setting a meeting inactive. Telecom is requesting this on behalf of an system service (e.g. Automotive service) or a device (e.g.Wearable). Note: Your app must stop using the microphone and playing incoming media when returning.

@ExtensionFunctionType @NonNull Function1<@NonNull CallControlScopeUnit> block

DSL interface block that will run when the call is ready

Throws
kotlin.UnsupportedOperationException

if the device is on an invalid build

java.util.concurrent.CancellationException

if the call failed to be added within 5000 milliseconds

registerAppWithTelecom

Added in 1.0.0-alpha03
@RequiresPermission(value = "android.permission.MANAGE_OWN_CALLS")
public final void registerAppWithTelecom(int capabilities)

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.

Throws
kotlin.UnsupportedOperationException

if the device is on an invalid build