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 registerPhoneAccount(PhoneAccount) for more information.

System managed ConnectionServices must be enabled by the user in the phone app settings before Telecom will bind to them. Self-manged ConnectionServices must be granted the appropriate permission 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 addNewIncomingCall(PhoneAccountHandle, Bundle). The ConnectionService can then expect a call to onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest) or onCreateOutgoingConnection(PhoneAccountHandle, 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.

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 RemoteConnection createRemoteIncomingConnection(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)

Ask some other ConnectionService to create a RemoteConnection given an incoming 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.

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.

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
String SERVICE_INTERFACE

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

Constant Value: "android.telecom.ConnectionService"

Public constructors

ConnectionService

added in API level 23
ConnectionService ()

Public methods

addConference

added in API level 23
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 destroy() is invoked on the conference instance.

Parameters
conference Conference: The new conference object.

addExistingConnection

added in API level 23
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
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

void connectionServiceFocusReleased ()

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

createRemoteIncomingConnection

added in API level 23
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 CAPABILITY_CONNECTION_MANAGER and want to be able to manage SIM-based incoming calls.

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

request ConnectionRequest: Details about the incoming call.

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

createRemoteOutgoingConnection

added in API level 23
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 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(PhoneAccountHandle, ConnectionRequest).

request ConnectionRequest: Details about the outgoing call.

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

getAllConferences

added in API level 24
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
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
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
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

void onConnectionServiceFocusGained ()

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

onConnectionServiceFocusLost

void onConnectionServiceFocusLost ()

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

onCreateIncomingConnection

added in API level 23
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(PhoneAccountHandle, 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
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 isIncomingCallPermitted(PhoneAccountHandle) for more information.

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

request ConnectionRequest: The incoming connection request.

onCreateIncomingHandoverConnection

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 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 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 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.

onCreateOutgoingConnection

added in API level 23
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 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 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 createFailedConnection(DisconnectCause) to not handle the call.

onCreateOutgoingConnectionFailed

added in API level 26
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 isOutgoingCallPermitted(PhoneAccountHandle) for more information.

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

request ConnectionRequest: The outgoing connection request.

onCreateOutgoingHandoverConnection

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 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 handoverTo(PhoneAccountHandle, int, Bundle).

For a full discussion of the handover process and the APIs involved, see 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

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 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 HANDOVER_FAILURE_DEST_APP_REJECTED, HANDOVER_FAILURE_NOT_SUPPORTED, HANDOVER_FAILURE_USER_REJECTED, HANDOVER_FAILURE_ONGOING_EMERGENCY_CALL or HANDOVER_FAILURE_UNKNOWN.

onRemoteConferenceAdded

added in API level 23
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 CAPABILITY_CONNECTION_MANAGER.

Parameters
conference RemoteConference: The remote conference call.

onRemoteExistingConnectionAdded

added in API level 23
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
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.