Skip to content

Most visited

Recently visited

navigation

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

From class android.app.Service
From class android.content.Context
From interface android.content.ComponentCallbacks2

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

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

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

From class android.app.Service
From class android.content.ContextWrapper
From class android.content.Context
From class java.lang.Object
From interface android.content.ComponentCallbacks2
From interface android.content.ComponentCallbacks

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.

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.

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.

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.

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.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)