# Print output for @column tags ?> ConnectionService - Android SDK | Android Developers

Most visited

Recently visited

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 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 TelecomManager#addNewIncomingCall. 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 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.

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

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

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

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

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

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.

See also:

createRemoteIncomingConference

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

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

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

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

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

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

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

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

public void onConnectionServiceFocusGained ()

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

onConnectionServiceFocusLost

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.

onCreateIncomingConference

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

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

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

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

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

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. This value cannot be null.

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

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

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

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

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

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

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

public void onRemoteExistingConnectionAdded (RemoteConnection connection)

Called when an existing connection is added remotely.

Parameters
connection RemoteConnection: The existing connection which was added.

onUnbind

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.