ConnectionService


public abstract class ConnectionService
extends Service

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.telecom.ConnectionService


An abstract service that should be implemented by any apps which either:

  1. Can make phone calls (VoIP or otherwise) and want those calls to be integrated into the built-in phone app. Referred to as a system managed ConnectionService.
  2. Are a standalone calling app and don't want their calls to be integrated into the built-in phone app. Referred to as a self managed ConnectionService.
Once implemented, the ConnectionService needs to take the following steps so that Telecom will bind to it:

1. Registration in AndroidManifest.xml

 <service android:name="com.example.package.MyConnectionService"
    android:label="@string/some_label_for_my_connection_service"
    android:permission="android.permission.BIND_TELECOM_CONNECTION_SERVICE">
  <intent-filter>
   <action android:name="android.telecom.ConnectionService" />
  </intent-filter>
 </service>
 

2. Registration of PhoneAccount with TelecomManager.
See PhoneAccount and TelecomManager.registerPhoneAccount for more information.

System managed ConnectionServices must be enabled by the user in the phone app settings before Telecom will bind to them. Self-managed ConnectionServices must declare the Manifest.permission.MANAGE_OWN_CALLS permission in their manifest before Telecom will bind to them.

Once registered and enabled by the user in the phone app settings or granted permission, telecom will bind to a ConnectionService implementation when it wants that ConnectionService to place a call or the service has indicated that is has an incoming call through TelecomManager.addNewIncomingCall(PhoneAccountHandle, Bundle). The ConnectionService can then expect a call to onCreateIncomingConnection(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest) or onCreateOutgoingConnection(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest) wherein it should provide a new instance of a Connection object. It is through this Connection object that telecom receives state updates and the ConnectionService receives call-commands such as answer, reject, hold and disconnect.

When there are no more live calls, telecom will unbind from the ConnectionService.

Self-Managed Connection Services


A VoIP app can implement a ConnectionService to ensure that its calls are integrated into the Android platform. There are numerous benefits to using the Telecom APIs for a VoIP app:
  • Call concurrency is handled - the user is able to swap between calls in different apps and on the mobile network.
  • Simplified audio routing - the platform provides your app with a unified list of the audio routes which are available (e.g. Connection.onAvailableCallEndpointsChanged(List)) and a standardized way to switch audio routes (e.g. Connection.requestCallEndpointChange(CallEndpoint, Executor, OutcomeReceiver) ).
  • Bluetooth integration - your calls will be visible on and controllable via bluetooth devices (e.g. car head units and headsets).
  • Companion device integration - wearable devices such as watches which implement an InCallService can optionally subscribe to see self-managed calls. Similar to a bluetooth headunit, wearables will typically render your call using a generic call UX and provide the user with basic call controls such as hangup, answer, reject.
  • Automotive calling experiences - Android supports automotive optimized experiences which provides a means for calls to be controlled and viewed in an automobile; these experiences are capable of leveraging call metadata provided by your app.

Registering a Phone Account

Before your app can handle incoming or outgoing calls through Telecom it needs to register a PhoneAccount with Telecom indicating to the platform that your app is capable of calling.

Your app should create a new instance of PhoneAccount which meets the following requirements:

Your app should register the new PhoneAccount with Telecom using TelecomManager.registerPhoneAccount(PhoneAccount). PhoneAccounts persist across reboot. You can use TelecomManager.getOwnSelfManagedPhoneAccounts() to confirm the PhoneAccount you registered. Your app should generally only register a single PhoneAccount.

Implementing ConnectionService

Your app uses TelecomManager.placeCall(Uri, Bundle) to start new outgoing calls and TelecomManager.addNewIncomingCall(PhoneAccountHandle, Bundle) to report new incoming calls. Calling these APIs causes the Telecom stack to bind to your app's ConnectionService implementation. Telecom will either inform your app that it cannot handle a call request at the current time (i.e. there could be an ongoing emergency call, which means your app is not allowed to handle calls at the current time), or it will ask your app to create a new instance of Connection to represent a call in your app. Your app should implement the following ConnectionService methods:

Implementing a Connection

Your app should extend the Connection class to represent calls in your app. When you create new instances of your Connection, you should ensure the following properties are set on the new Connection instance returned by your ConnectionService:

How to Place Outgoing Calls

When your app wants to place an outgoing call it calls TelecomManager.placeCall(Uri, Bundle). You should specify a Uri to identify who the call is being placed to, and specify the PhoneAccountHandle associated with the PhoneAccount you registered for your app using TelecomManager.EXTRA_PHONE_ACCOUNT_HANDLE in the Bundle parameter.

Telecom will bind to your app's ConnectionService implementation and call either:

New outgoing calls will start in a Connection.STATE_DIALING state. This state indicates that your app is in the process of connecting the call to the other party.

Once the other party answers the call (or it is set up successfully), your app should call Connection.setActive() to inform Telecom that the call is now active.

How to Add Incoming Calls

When your app receives an incoming call, it should call TelecomManager.addNewIncomingCall(PhoneAccountHandle, Bundle). Set the PhoneAccountHandle parameter to the PhoneAccountHandle associated with your app's PhoneAccount.

Telecom will bind to your app's ConnectionService implementation and call either:

New incoming calls will start with a Connection.STATE_RINGING state. This state indicates that your app has a new incoming call pending. Telecom will NOT play a ringtone or post a notification for your app. It is up to your app to post an incoming call notification with an associated ringtone. Telecom will call Connection.onShowIncomingCallUi() on the Connection when your app can post its incoming call notification. See the docs for more information on how to post the notification.

Your incoming call notification (or full screen UI) will typically have an "answer" and "decline" action which the user chooses. When your app receives the "answer" or "decline" PendingIntent, you should must call either Connection.setActive() to inform Telecom that the call was answered, or Connection.setDisconnected(DisconnectCause) to inform Telecom that the call was rejected. If the call was rejected, supply an instance of DisconnectCause with DisconnectCause.REJECTED, and then call Connection.destroy().

In addition to handling requests to answer or decline the call via notification actions, your app should also be implement the Connection.onAnswer(int) and Connection.onAnswer() methods on the Connection. These will be raised if the user answers your call via a Bluetooth device or another device like a wearable or automotive calling UX. In response, your app should call Connection.setActive() to inform Telecom that the call was answered.

Additionally, your app should implement Connection.onReject() to handle requests to reject the call which are raised via Bluetooth or other calling surfaces. Your app should call Connection.setDisconnected(DisconnectCause) and supply an instance of DisconnectCause with DisconnectCause.REJECTED in this case.

Ending Calls

When an ongoing active call (incoming or outgoing) has ended, your app is responsible for informing Telecom that the call ended.

Your app calls:

Similar to answering incoming calls, requests to disconnect your call may originate from outside your app. You can handle these by implementing Connection.onDisconnect(). Your app should call Connection.setDisconnected(DisconnectCause) with an instance of DisconnectCause and reason DisconnectCause.LOCAL to indicate to Telecom that your app has disconnected the call as requested based on the user's request.

Holding and Unholding Calls

When your app specifies Connection.CAPABILITY_SUPPORT_HOLD and Connection.CAPABILITY_HOLD on your Connection instance, it is telling Telecom that your calls can be placed into a suspended, or "held" state if required. If your app supports holding its calls, it will be possible for the user to switch between calls in your app and holdable calls in another app or on the mobile network. If your app does not support holding its calls, you may receive a request to disconnect the call from Telecom if the user opts to answer an incoming call in another app or on the mobile network; this ensures that the user can only be in one call at a time.

Your app is free to change a call between the held and active state using Connection.setOnHold() and Connection.setActive().

Your app may receive a request from Telecom to hold or unhold a call via Connection.onHold() and Connection.onUnhold(). Telecom can ask your app to hold or unhold its Connection either if the user requests this action through another calling surface such as Bluetooth, or if the user answers or switches to a call in a different app or on the mobile network.

When your app receives an Connection.onHold() it must call Connection.setOnHold() to inform Telecom that the call has been held successfully.

When your app receives an Connection.onUnhold() it must call Connection.setActive() to inform Telecom that the call has been resumed successfully.

Summary

Constants

String SERVICE_INTERFACE

The Intent that must be declared as handled by the service.

Inherited constants

Public constructors

ConnectionService()

Public methods

final void addConference(Conference conference)

Adds a new conference call.

final void addExistingConnection(PhoneAccountHandle phoneAccountHandle, Connection connection)

Adds a connection created by the ConnectionService and informs telecom of the new connection.

final void conferenceRemoteConnections(RemoteConnection remoteConnection1, RemoteConnection remoteConnection2)

Indicates to the relevant RemoteConnectionService that the specified RemoteConnections should be merged into a conference call.

final void connectionServiceFocusReleased()

Call to inform Telecom that your ConnectionService has released call resources (e.g microphone, camera).

final RemoteConference createRemoteIncomingConference(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)

Ask some other ConnectionService to create a RemoteConference given an incoming request.

final RemoteConnection createRemoteIncomingConnection(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)

Ask some other ConnectionService to create a RemoteConnection given an incoming request.

final RemoteConference createRemoteOutgoingConference(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)

Ask some other ConnectionService to create a RemoteConference given an outgoing request.

final RemoteConnection createRemoteOutgoingConnection(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)

Ask some other ConnectionService to create a RemoteConnection given an outgoing request.

final Collection<Conference> getAllConferences()

Returns all the active Conferences for which this ConnectionService has taken responsibility.

final Collection<Connection> getAllConnections()

Returns all the active Connections for which this ConnectionService has taken responsibility.

final IBinder onBind(Intent intent)

Return the communication channel to the service.

void onConference(Connection connection1, Connection connection2)

Conference two specified connections.

void onConnectionServiceFocusGained()

Called when the ConnectionService has gained the call focus.

void onConnectionServiceFocusLost()

Called when the ConnectionService has lost the call focus.

void onCreateConferenceComplete(Conference conference)

Called by Telecom after the Conference returned by onCreateIncomingConference(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest) or onCreateOutgoingConference(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest) has been added to the ConnectionService and sent to Telecom.

void onCreateConnectionComplete(Connection connection)

Called by Telecom after the Connection returned by onCreateIncomingConnection(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest) or onCreateOutgoingConnection(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest) has been added to the ConnectionService and sent to Telecom.

Conference onCreateIncomingConference(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)

Create a Conference given an incoming request.

void onCreateIncomingConferenceFailed(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)

Called by Telecom to inform the ConnectionService that its request to create a new incoming Conference was denied.

Connection onCreateIncomingConnection(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)

Create a Connection given an incoming request.

void onCreateIncomingConnectionFailed(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)

Called by Telecom to inform the ConnectionService that its request to create a new incoming Connection was denied.

Connection onCreateIncomingHandoverConnection(PhoneAccountHandle fromPhoneAccountHandle, ConnectionRequest request)

Called by Telecom to request that a ConnectionService creates an instance of an incoming handover Connection.

Conference onCreateOutgoingConference(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)

Create a Conference given an outgoing request.

void onCreateOutgoingConferenceFailed(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)

Called by Telecom to inform the ConnectionService that its request to create a new outgoing Conference was denied.

Connection onCreateOutgoingConnection(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)

Create a Connection given an outgoing request.

void onCreateOutgoingConnectionFailed(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)

Called by Telecom to inform the ConnectionService that its request to create a new outgoing Connection was denied.

Connection onCreateOutgoingHandoverConnection(PhoneAccountHandle fromPhoneAccountHandle, ConnectionRequest request)

Called by Telecom to request that a ConnectionService creates an instance of an outgoing handover Connection.

void onHandoverFailed(ConnectionRequest request, int error)

Called by Telecom in response to a TelecomManager#acceptHandover() invocation which failed.

void onRemoteConferenceAdded(RemoteConference conference)

Indicates that a remote conference has been created for existing RemoteConnections.

void onRemoteExistingConnectionAdded(RemoteConnection connection)

Called when an existing connection is added remotely.

boolean onUnbind(Intent intent)

Called when all clients have disconnected from a particular interface published by the service.

Inherited methods

Constants

SERVICE_INTERFACE

Added in API level 23
public static final String SERVICE_INTERFACE

The Intent that must be declared as handled by the service.

Constant Value: "android.telecom.ConnectionService"

Public constructors

ConnectionService

public ConnectionService ()

Public methods

addConference

Added in API level 23
public final void addConference (Conference conference)

Adds a new conference call. When a conference call is created either as a result of an explicit request via onConference(Connection, Connection) or otherwise, the connection service should supply an instance of Conference by invoking this method. A conference call provided by this method will persist until Conference.destroy is invoked on the conference instance.

Parameters
conference Conference: The new conference object.

addExistingConnection

Added in API level 23
public final void addExistingConnection (PhoneAccountHandle phoneAccountHandle, 
                Connection connection)

Adds a connection created by the ConnectionService and informs telecom of the new connection.

Parameters
phoneAccountHandle PhoneAccountHandle: The phone account handle for the connection.

connection Connection: The connection to add.

conferenceRemoteConnections

Added in API level 23
public final void conferenceRemoteConnections (RemoteConnection remoteConnection1, 
                RemoteConnection remoteConnection2)

Indicates to the relevant RemoteConnectionService that the specified RemoteConnections should be merged into a conference call.

If the conference request is successful, the method onRemoteConferenceAdded(RemoteConference) will be invoked.

Parameters
remoteConnection1 RemoteConnection: The first of the remote connections to conference.

remoteConnection2 RemoteConnection: The second of the remote connections to conference.

connectionServiceFocusReleased

Added in API level 28
public final void connectionServiceFocusReleased ()

Call to inform Telecom that your ConnectionService has released call resources (e.g microphone, camera).

The ConnectionService will be disconnected when it failed to call this method within 5 seconds after onConnectionServiceFocusLost() is called.

createRemoteIncomingConference

Added in API level 31
public final RemoteConference createRemoteIncomingConference (PhoneAccountHandle connectionManagerPhoneAccount, 
                ConnectionRequest request)

Ask some other ConnectionService to create a RemoteConference given an incoming request. This is used by ConnectionServices that are registered with PhoneAccount.CAPABILITY_ADHOC_CONFERENCE_CALLING.

Parameters
connectionManagerPhoneAccount PhoneAccountHandle: See description at onCreateOutgoingConnection(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest). This value may be null.

request ConnectionRequest: Details about the incoming conference call. This value may be null.

Returns
RemoteConference The RemoteConference object to satisfy this call, or null to not handle the call.

createRemoteIncomingConnection

Added in API level 23
public final RemoteConnection createRemoteIncomingConnection (PhoneAccountHandle connectionManagerPhoneAccount, 
                ConnectionRequest request)

Ask some other ConnectionService to create a RemoteConnection given an incoming request. This is used by ConnectionServices that are registered with PhoneAccount.CAPABILITY_CONNECTION_MANAGER and want to be able to manage SIM-based incoming calls.

Parameters
connectionManagerPhoneAccount PhoneAccountHandle: See description at onCreateOutgoingConnection(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest). This value cannot be null.

request ConnectionRequest: Details about the incoming call. This value cannot be null.

Returns
RemoteConnection The Connection object to satisfy this call, or null to not handle the call.

createRemoteOutgoingConference

Added in API level 31
public final RemoteConference createRemoteOutgoingConference (PhoneAccountHandle connectionManagerPhoneAccount, 
                ConnectionRequest request)

Ask some other ConnectionService to create a RemoteConference given an outgoing request. This is used by ConnectionServices that are registered with PhoneAccount.CAPABILITY_ADHOC_CONFERENCE_CALLING.

Parameters
connectionManagerPhoneAccount PhoneAccountHandle: See description at onCreateOutgoingConnection(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest). This value may be null.

request ConnectionRequest: Details about the outgoing conference call. This value may be null.

Returns
RemoteConference The RemoteConference object to satisfy this call, or null to not handle the call.

createRemoteOutgoingConnection

Added in API level 23
public final RemoteConnection createRemoteOutgoingConnection (PhoneAccountHandle connectionManagerPhoneAccount, 
                ConnectionRequest request)

Ask some other ConnectionService to create a RemoteConnection given an outgoing request. This is used by ConnectionServices that are registered with PhoneAccount.CAPABILITY_CONNECTION_MANAGER and want to be able to use the SIM-based ConnectionService to place its outgoing calls.

Parameters
connectionManagerPhoneAccount PhoneAccountHandle: See description at onCreateOutgoingConnection(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest). This value cannot be null.

request ConnectionRequest: Details about the outgoing call. This value cannot be null.

Returns
RemoteConnection The Connection object to satisfy this call, or null to not handle the call.

getAllConferences

Added in API level 24
public final Collection<Conference> getAllConferences ()

Returns all the active Conferences for which this ConnectionService has taken responsibility.

Returns
Collection<Conference> A collection of Conferences created by this ConnectionService.

getAllConnections

Added in API level 23
public final Collection<Connection> getAllConnections ()

Returns all the active Connections for which this ConnectionService has taken responsibility.

Returns
Collection<Connection> A collection of Connections created by this ConnectionService.

onBind

Added in API level 23
public final IBinder onBind (Intent intent)

Return the communication channel to the service. May return null if clients can not bind to the service. The returned IBinder is usually for a complex interface that has been described using aidl.

Note that unlike other application components, calls on to the IBinder interface returned here may not happen on the main thread of the process. More information about the main thread can be found in Processes and Threads.

Parameters
intent Intent: The Intent that was used to bind to this service, as given to Context.bindService. Note that any extras that were included with the Intent at that point will not be seen here.

Returns
IBinder Return an IBinder through which clients can call on to the service.

onConference

Added in API level 23
public void onConference (Connection connection1, 
                Connection connection2)

Conference two specified connections. Invoked when the user has made a request to merge the specified connections into a conference call. In response, the connection service should create an instance of Conference and pass it into addConference(Conference).

Parameters
connection1 Connection: A connection to merge into a conference call.

connection2 Connection: A connection to merge into a conference call.

onConnectionServiceFocusGained

Added in API level 28
public void onConnectionServiceFocusGained ()

Called when the ConnectionService has gained the call focus. The ConnectionService can acquire the call resources at this time.

onConnectionServiceFocusLost

Added in API level 28
public void onConnectionServiceFocusLost ()

Called when the ConnectionService has lost the call focus. The ConnectionService should release the call resources and invokes ConnectionService.connectionServiceFocusReleased() to inform telecom that it has released the call resources.

onCreateConferenceComplete

public void onCreateConferenceComplete (Conference conference)

Called by Telecom after the Conference returned by onCreateIncomingConference(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest) or onCreateOutgoingConference(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest) has been added to the ConnectionService and sent to Telecom.

Parameters
conference Conference: the Conference which was added to Telecom. This value cannot be null.

onCreateConnectionComplete

public void onCreateConnectionComplete (Connection connection)

Called by Telecom after the Connection returned by onCreateIncomingConnection(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest) or onCreateOutgoingConnection(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest) has been added to the ConnectionService and sent to Telecom.

Parameters
connection Connection: the Connection which was added to Telecom. This value cannot be null.

onCreateIncomingConference

Added in API level 31
public Conference onCreateIncomingConference (PhoneAccountHandle connectionManagerPhoneAccount, 
                ConnectionRequest request)

Create a Conference given an incoming request. This is used to attach to an incoming conference call initiated via TelecomManager.addNewIncomingConference(PhoneAccountHandle, Bundle).

Parameters
connectionManagerPhoneAccount PhoneAccountHandle: See description at onCreateOutgoingConnection(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest). This value cannot be null.

request ConnectionRequest: Details about the incoming conference call. This value cannot be null.

Returns
Conference The Conference object to satisfy this call. If the conference attempt is failed, the return value will be a result of an invocation of Connection.createFailedConnection(DisconnectCause). Return null if the ConnectionService cannot handle the call.

onCreateIncomingConferenceFailed

Added in API level 31
public void onCreateIncomingConferenceFailed (PhoneAccountHandle connectionManagerPhoneAccount, 
                ConnectionRequest request)

Called by Telecom to inform the ConnectionService that its request to create a new incoming Conference was denied.

Used when a self-managed ConnectionService attempts to create a new incoming Conference, but Telecom has determined that the call cannot be allowed at this time. The ConnectionService is responsible for silently rejecting the new incoming Conference.

See TelecomManager.isIncomingCallPermitted(PhoneAccountHandle) for more information.

Parameters
connectionManagerPhoneAccount PhoneAccountHandle: See description at onCreateOutgoingConnection(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest). This value may be null.

request ConnectionRequest: The incoming connection request. This value may be null.

onCreateIncomingConnection

Added in API level 23
public Connection onCreateIncomingConnection (PhoneAccountHandle connectionManagerPhoneAccount, 
                ConnectionRequest request)

Create a Connection given an incoming request. This is used to attach to existing incoming calls.

Parameters
connectionManagerPhoneAccount PhoneAccountHandle: See description at onCreateOutgoingConnection(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest).

request ConnectionRequest: Details about the incoming call.

Returns
Connection The Connection object to satisfy this call, or null to not handle the call.

onCreateIncomingConnectionFailed

Added in API level 26
public void onCreateIncomingConnectionFailed (PhoneAccountHandle connectionManagerPhoneAccount, 
                ConnectionRequest request)

Called by Telecom to inform the ConnectionService that its request to create a new incoming Connection was denied.

Used when a self-managed ConnectionService attempts to create a new incoming Connection, but Telecom has determined that the call cannot be allowed at this time. The ConnectionService is responsible for silently rejecting the new incoming Connection.

See TelecomManager.isIncomingCallPermitted(PhoneAccountHandle) for more information.

Parameters
connectionManagerPhoneAccount PhoneAccountHandle: See description at onCreateOutgoingConnection(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest).

request ConnectionRequest: The incoming connection request.

onCreateIncomingHandoverConnection

Added in API level 28
public Connection onCreateIncomingHandoverConnection (PhoneAccountHandle fromPhoneAccountHandle, 
                ConnectionRequest request)

Called by Telecom to request that a ConnectionService creates an instance of an incoming handover Connection.

A call handover is the process where an ongoing call is transferred from one app (i.e. ConnectionService to another app. The user could, for example, choose to continue a mobile network call in a video calling app. The mobile network call via the Telephony stack is referred to as the source of the handover, and the video calling app is referred to as the destination.

When considering a handover scenario the initiating device is where a user initiated the handover process (e.g. by calling Call.handoverTo(PhoneAccountHandle, int, Bundle), and the other device is considered the receiving device.

This method is called on the destination app on the receiving device when the destination app calls TelecomManager.acceptHandover(Uri, int, PhoneAccountHandle) to accept an incoming handover from the initiating device.

For a full discussion of the handover process and the APIs involved, see Call.handoverTo(PhoneAccountHandle, int, Bundle).

Implementations of this method should return an instance of Connection which represents the handover. The code below shows an example of how this is done.

 public Connection onCreateIncomingHandoverConnection(PhoneAccountHandle
     fromPhoneAccountHandle, ConnectionRequest request) {
   // Given that your app requested to accept the handover, you should not return null here.
   MyConnection connection = new MyConnection();
   connection.setAddress(request.getAddress(), TelecomManager.PRESENTATION_ALLOWED);
   connection.setVideoState(request.getVideoState());
   return connection;
 }
 
 

Parameters
fromPhoneAccountHandle PhoneAccountHandle: PhoneAccountHandle associated with the ConnectionService which needs to handover the call.

request ConnectionRequest: Details about the call which needs to be handover.

Returns
Connection Connection instance corresponding to the handover call.

onCreateOutgoingConference

Added in API level 31
public Conference onCreateOutgoingConference (PhoneAccountHandle connectionManagerPhoneAccount, 
                ConnectionRequest request)

Create a Conference given an outgoing request. This is used to initiate new outgoing conference call requested via TelecomManager.startConference(List, Bundle).

Parameters
connectionManagerPhoneAccount PhoneAccountHandle: The connection manager account to use for managing this call.

If this parameter is not null, it means that this ConnectionService has registered one or more PhoneAccounts having PhoneAccount.CAPABILITY_CONNECTION_MANAGER. This parameter will contain one of these PhoneAccounts, while the request will contain another (usually but not always distinct) PhoneAccount to be used for actually making the connection.

If this parameter is null, it means that this ConnectionService is being asked to make a direct connection. The ConnectionRequest.getAccountHandle() of parameter request will be a PhoneAccount registered by this ConnectionService to use for making the connection.

request ConnectionRequest: Details about the outgoing call. This value cannot be null.

Returns
Conference The Conference object to satisfy this call. If the conference attempt is failed, the return value will be a result of an invocation of Connection.createFailedConnection(DisconnectCause). Return null if the ConnectionService cannot handle the call.

onCreateOutgoingConferenceFailed

Added in API level 31
public void onCreateOutgoingConferenceFailed (PhoneAccountHandle connectionManagerPhoneAccount, 
                ConnectionRequest request)

Called by Telecom to inform the ConnectionService that its request to create a new outgoing Conference was denied.

Used when a self-managed ConnectionService attempts to create a new outgoing Conference, but Telecom has determined that the call cannot be placed at this time. The ConnectionService is responisible for informing the user that the Conference cannot be made at this time.

See TelecomManager.isOutgoingCallPermitted(PhoneAccountHandle) for more information.

Parameters
connectionManagerPhoneAccount PhoneAccountHandle: See description at onCreateOutgoingConnection(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest). This value cannot be null.

request ConnectionRequest: The outgoing connection request. This value cannot be null.

onCreateOutgoingConnection

Added in API level 23
public Connection onCreateOutgoingConnection (PhoneAccountHandle connectionManagerPhoneAccount, 
                ConnectionRequest request)

Create a Connection given an outgoing request. This is used to initiate new outgoing calls.

Parameters
connectionManagerPhoneAccount PhoneAccountHandle: The connection manager account to use for managing this call.

If this parameter is not null, it means that this ConnectionService has registered one or more PhoneAccounts having PhoneAccount.CAPABILITY_CONNECTION_MANAGER. This parameter will contain one of these PhoneAccounts, while the request will contain another (usually but not always distinct) PhoneAccount to be used for actually making the connection.

If this parameter is null, it means that this ConnectionService is being asked to make a direct connection. The ConnectionRequest.getAccountHandle() of parameter request will be a PhoneAccount registered by this ConnectionService to use for making the connection.

request ConnectionRequest: Details about the outgoing call.

Returns
Connection The Connection object to satisfy this call, or the result of an invocation of Connection.createFailedConnection(DisconnectCause) to not handle the call.

onCreateOutgoingConnectionFailed

Added in API level 26
public void onCreateOutgoingConnectionFailed (PhoneAccountHandle connectionManagerPhoneAccount, 
                ConnectionRequest request)

Called by Telecom to inform the ConnectionService that its request to create a new outgoing Connection was denied.

Used when a self-managed ConnectionService attempts to create a new outgoing Connection, but Telecom has determined that the call cannot be placed at this time. The ConnectionService is responisible for informing the user that the Connection cannot be made at this time.

See TelecomManager.isOutgoingCallPermitted(PhoneAccountHandle) for more information.

Parameters
connectionManagerPhoneAccount PhoneAccountHandle: See description at onCreateOutgoingConnection(android.telecom.PhoneAccountHandle, android.telecom.ConnectionRequest).

request ConnectionRequest: The outgoing connection request.

onCreateOutgoingHandoverConnection

Added in API level 28
public Connection onCreateOutgoingHandoverConnection (PhoneAccountHandle fromPhoneAccountHandle, 
                ConnectionRequest request)

Called by Telecom to request that a ConnectionService creates an instance of an outgoing handover Connection.

A call handover is the process where an ongoing call is transferred from one app (i.e. ConnectionService to another app. The user could, for example, choose to continue a mobile network call in a video calling app. The mobile network call via the Telephony stack is referred to as the source of the handover, and the video calling app is referred to as the destination.

When considering a handover scenario the initiating device is where a user initiated the handover process (e.g. by calling Call.handoverTo(PhoneAccountHandle, int, Bundle), and the other device is considered the receiving device.

This method is called on the destination ConnectionService on initiating device when the user initiates a handover request from one app to another. The user request originates in the InCallService via Call.handoverTo(PhoneAccountHandle, int, Bundle).

For a full discussion of the handover process and the APIs involved, see Call.handoverTo(PhoneAccountHandle, int, Bundle).

Implementations of this method should return an instance of Connection which represents the handover. If your app does not wish to accept a handover to it at this time, you can return null. The code below shows an example of how this is done.

 public Connection onCreateIncomingHandoverConnection(PhoneAccountHandle
     fromPhoneAccountHandle, ConnectionRequest request) {
   if (!isHandoverAvailable()) {
       return null;
   }
   MyConnection connection = new MyConnection();
   connection.setAddress(request.getAddress(), TelecomManager.PRESENTATION_ALLOWED);
   connection.setVideoState(request.getVideoState());
   return connection;
 }
 
 

Parameters
fromPhoneAccountHandle PhoneAccountHandle: PhoneAccountHandle associated with the ConnectionService which needs to handover the call.

request ConnectionRequest: Details about the call to handover.

Returns
Connection Connection instance corresponding to the handover call.

onHandoverFailed

Added in API level 28
public void onHandoverFailed (ConnectionRequest request, 
                int error)

Called by Telecom in response to a TelecomManager#acceptHandover() invocation which failed.

For a full discussion of the handover process and the APIs involved, see Call.handoverTo(PhoneAccountHandle, int, Bundle)

Parameters
request ConnectionRequest: Details about the call which failed to handover.

error int: Reason for handover failure. Will be one of the Value is Call.Callback.HANDOVER_FAILURE_DEST_APP_REJECTED, Call.Callback.HANDOVER_FAILURE_NOT_SUPPORTED, Call.Callback.HANDOVER_FAILURE_USER_REJECTED, Call.Callback.HANDOVER_FAILURE_ONGOING_EMERGENCY_CALL, or Call.Callback.HANDOVER_FAILURE_UNKNOWN

onRemoteConferenceAdded

Added in API level 23
public void onRemoteConferenceAdded (RemoteConference conference)

Indicates that a remote conference has been created for existing RemoteConnections. When this method is invoked, this ConnectionService should create its own representation of the conference call and send it to telecom using addConference(Conference).

This is only relevant to ConnectionServices which are registered with PhoneAccount.CAPABILITY_CONNECTION_MANAGER.

Parameters
conference RemoteConference: The remote conference call.

onRemoteExistingConnectionAdded

Added in API level 23
public void onRemoteExistingConnectionAdded (RemoteConnection connection)

Called when an existing connection is added remotely.

Parameters
connection RemoteConnection: The existing connection which was added.

onUnbind

Added in API level 23
public boolean onUnbind (Intent intent)

Called when all clients have disconnected from a particular interface published by the service. The default implementation does nothing and returns false.

Parameters
intent Intent: The Intent that was used to bind to this service, as given to Context.bindService. Note that any extras that were included with the Intent at that point will not be seen here.

Returns
boolean Return true if you would like to have the service's onRebind(Intent) method later called when new clients bind to it.