Most visited

Recently visited

Added in API level 23

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 can make phone calls (VoIP or otherwise) and want those calls to be integrated into the built-in phone app. Once implemented, the ConnectionService needs two additional steps before it will be integrated into the phone app:

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.

Once registered and enabled by the user in the phone app settings, 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.

Connection onCreateOutgoingConnection(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)

Create a Connection given an outgoing request.

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

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.

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.

Hooray!