ConnectionService
abstract class ConnectionService : Service
kotlin.Any | ||||
↳ | android.content.Context | |||
↳ | android.content.ContextWrapper | |||
↳ | android.app.Service | |||
↳ | android.telecom.ConnectionService |
An abstract service that should be implemented by any apps which either:
- 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
. - 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
.
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 ConnectionService
s must be enabled by the user in the phone app settings before Telecom will bind to them. Self-managed ConnectionService
s must declare the android.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
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.
android.telecom.Connection#onAvailableCallEndpointsChanged(List)
) and a standardized way to switch audio routes (e.g.android.telecom.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 aPhoneAccount
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:
- Has
PhoneAccount.CAPABILITY_SELF_MANAGED
(set usingPhoneAccount.Builder.setCapabilities(int)
). This indicates to Telecom that your app will report calls but that it provides a primary UI for the calls by itself. - Provide a unique identifier for the
PhoneAccount
via thePhoneAccountHandle.getId()
attribute. As per thePhoneAccountHandle
documentation, you should NOT use an identifier which contains PII or other sensitive information. A typical choice is a UUID.
PhoneAccount
with Telecom using TelecomManager.registerPhoneAccount(PhoneAccount)
. PhoneAccount
s 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 usesTelecomManager.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:
ConnectionService.onCreateOutgoingConnection(PhoneAccountHandle,
- called by Telecom to ask your app to make a newConnection
to represent an outgoing call your app requested viaTelecomManager.placeCall(Uri, Bundle)
.- <
ConnectionService.onCreateOutgoingConnectionFailed(PhoneAccountHandle,
- called by Telecom to inform your app that a call it reported viaTelecomManager.placeCall(Uri, Bundle)
cannot be handled at this time. Your app should NOT place a call at the current time. ConnectionService.onCreateIncomingConnection(PhoneAccountHandle,
- called by Telecom to ask your app to make a newConnection
to represent an incoming call your app reported viaTelecomManager.addNewIncomingCall(PhoneAccountHandle, Bundle)
.ConnectionService.onCreateIncomingConnectionFailed(PhoneAccountHandle,
- called by Telecom to inform your app that an incoming call it reported viaTelecomManager.addNewIncomingCall(PhoneAccountHandle, Bundle)
cannot be handled at this time. Your app should NOT post a new incoming call notification and should silently reject the call.
Implementing a Connection
Your app should extend theConnection
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
:
Connection.setAddress(Uri, int)
- the identifier for the other party. For apps that user phone numbers theUri
can be aPhoneAccount.SCHEME_TEL
URI representing the phone number.Connection.setCallerDisplayName(String, int)
- the display name of the other party. This is what will be shown on Bluetooth devices and other calling surfaces such as wearable devices. This is particularly important for calls that do not use a phone number to identify the caller or called party.Connection.setConnectionProperties(int)
- ensure you setConnection.PROPERTY_SELF_MANAGED
to identify to the platform that the call is handled by your app.Connection.setConnectionCapabilities(int)
- if your app supports making calls inactive (i.e. holding calls) you should getConnection.CAPABILITY_SUPPORT_HOLD
andConnection.CAPABILITY_HOLD
to indicate to the platform that you calls can potentially be held for concurrent calling scenarios.Connection.setAudioModeIsVoip(boolean)
- set totrue
to ensure that the platform knows your call is a VoIP call.- For newly created
Connection
instances, do NOT change the state of your call usingConnection.setActive()
,Connection.setOnHold()
until the call is added to Telecom (ie you have returned it viaConnectionService.onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)
orConnectionService.onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)
).
How to Place Outgoing Calls
When your app wants to place an outgoing call it callsTelecomManager.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:
ConnectionService.onCreateOutgoingConnection(PhoneAccountHandle,
- theConnectionRequest.getAddress()
will match the address you specified when placing the call. You should return a new instance of your app'sConnection
class to represent the outgoing call.ConnectionService.onCreateOutgoingConnectionFailed(PhoneAccountHandle,
- your app should not place the call at this time; the call should be cancelled and the user informed that the call cannot be placed.
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 callTelecomManager.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:
ConnectionService.onCreateIncomingConnection(PhoneAccountHandle,
- You should return a new instance of your app'sConnection
class to represent the incoming call.ConnectionService.onCreateIncomingConnectionFailed(PhoneAccountHandle,
- your app should not receive the call at this time; the call should be rejected silently; the user may be informed of a missed call.
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" android.app.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:
Connection.setDisconnected(DisconnectCause)
- this informs Telecom that the call has terminated. You should provide a new instance ofDisconnectCause
with eitherDisconnectCause.LOCAL
orDisconnectCause.REMOTE
to indicate where the call disconnection took place.DisconnectCause.LOCAL
indicates that the call terminated in your app on the current device (i.e. via user action), whereDisconnectCause.REMOTE
indicates that the call terminates on the remote device.Connection.destroy()
- this informs Telecom that your call instance can be cleaned up. You should always call this when you are finished with a call.
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 specifiesConnection.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 | |
---|---|
static String |
The |
Inherited constants | |
---|---|
Public constructors | |
---|---|
Public methods | |
---|---|
Unit |
addConference(conference: Conference!) Adds a new conference call. |
Unit |
addExistingConnection(phoneAccountHandle: PhoneAccountHandle!, connection: Connection!) Adds a connection created by the |
Unit |
conferenceRemoteConnections(remoteConnection1: RemoteConnection!, remoteConnection2: RemoteConnection!) Indicates to the relevant |
Unit |
Call to inform Telecom that your |
RemoteConference? |
createRemoteIncomingConference(connectionManagerPhoneAccount: PhoneAccountHandle?, request: ConnectionRequest?) Ask some other |
RemoteConnection? |
createRemoteIncomingConnection(connectionManagerPhoneAccount: PhoneAccountHandle, request: ConnectionRequest) Ask some other |
RemoteConference? |
createRemoteOutgoingConference(connectionManagerPhoneAccount: PhoneAccountHandle?, request: ConnectionRequest?) Ask some other |
RemoteConnection? |
createRemoteOutgoingConnection(connectionManagerPhoneAccount: PhoneAccountHandle, request: ConnectionRequest) Ask some other |
MutableCollection<Conference!>! |
Returns all the active |
MutableCollection<Connection!>! |
Returns all the active |
IBinder? |
Return the communication channel to the service. |
open Unit |
onConference(connection1: Connection!, connection2: Connection!) Conference two specified connections. |
open Unit |
Called when the |
open Unit |
Called when the |
open Unit |
onCreateConferenceComplete(conference: Conference) Called by Telecom after the |
open Unit |
onCreateConnectionComplete(connection: Connection) Called by Telecom after the |
open Conference? |
onCreateIncomingConference(connectionManagerPhoneAccount: PhoneAccountHandle, request: ConnectionRequest) Create a |
open Unit |
onCreateIncomingConferenceFailed(connectionManagerPhoneAccount: PhoneAccountHandle?, request: ConnectionRequest?) Called by Telecom to inform the |
open Connection! |
onCreateIncomingConnection(connectionManagerPhoneAccount: PhoneAccountHandle!, request: ConnectionRequest!) Create a |
open Unit |
onCreateIncomingConnectionFailed(connectionManagerPhoneAccount: PhoneAccountHandle!, request: ConnectionRequest!) Called by Telecom to inform the |
open Connection! |
onCreateIncomingHandoverConnection(fromPhoneAccountHandle: PhoneAccountHandle!, request: ConnectionRequest!) Called by Telecom to request that a |
open Conference? |
onCreateOutgoingConference(connectionManagerPhoneAccount: PhoneAccountHandle, request: ConnectionRequest) Create a |
open Unit |
onCreateOutgoingConferenceFailed(connectionManagerPhoneAccount: PhoneAccountHandle, request: ConnectionRequest) Called by Telecom to inform the |
open Connection! |
onCreateOutgoingConnection(connectionManagerPhoneAccount: PhoneAccountHandle!, request: ConnectionRequest!) Create a |
open Unit |
onCreateOutgoingConnectionFailed(connectionManagerPhoneAccount: PhoneAccountHandle!, request: ConnectionRequest!) Called by Telecom to inform the |
open Connection! |
onCreateOutgoingHandoverConnection(fromPhoneAccountHandle: PhoneAccountHandle!, request: ConnectionRequest!) Called by Telecom to request that a |
open Unit |
onHandoverFailed(request: ConnectionRequest!, error: Int) Called by Telecom in response to a |
open Unit |
onRemoteConferenceAdded(conference: RemoteConference!) Indicates that a remote conference has been created for existing |
open Unit |
onRemoteExistingConnectionAdded(connection: RemoteConnection!) Called when an existing connection is added remotely. |
open Boolean |
Called when all clients have disconnected from a particular interface published by the service. |
Inherited functions | |
---|---|
Constants
SERVICE_INTERFACE
static val SERVICE_INTERFACE: String
The Intent
that must be declared as handled by the service.
Value: "android.telecom.ConnectionService"
Public constructors
ConnectionService
ConnectionService()
Public methods
addConference
fun addConference(conference: Conference!): Unit
Adds a new conference call. When a conference call is created either as a result of an explicit request via onConference
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
fun addExistingConnection(
phoneAccountHandle: PhoneAccountHandle!,
connection: Connection!
): Unit
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
fun conferenceRemoteConnections(
remoteConnection1: RemoteConnection!,
remoteConnection2: RemoteConnection!
): Unit
Indicates to the relevant RemoteConnectionService
that the specified RemoteConnection
s should be merged into a conference call.
If the conference request is successful, the method onRemoteConferenceAdded
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
fun connectionServiceFocusReleased(): Unit
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
fun createRemoteIncomingConference(
connectionManagerPhoneAccount: PhoneAccountHandle?,
request: ConnectionRequest?
): RemoteConference?
Ask some other ConnectionService
to create a RemoteConference
given an incoming request. This is used by ConnectionService
s 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 . |
Return | |
---|---|
RemoteConference? |
The RemoteConference object to satisfy this call, or null to not handle the call. |
createRemoteIncomingConnection
fun createRemoteIncomingConnection(
connectionManagerPhoneAccount: PhoneAccountHandle,
request: ConnectionRequest
): RemoteConnection?
Ask some other ConnectionService
to create a RemoteConnection
given an incoming request. This is used by ConnectionService
s 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 . |
Return | |
---|---|
RemoteConnection? |
The Connection object to satisfy this call, or null to not handle the call. |
createRemoteOutgoingConference
fun createRemoteOutgoingConference(
connectionManagerPhoneAccount: PhoneAccountHandle?,
request: ConnectionRequest?
): RemoteConference?
Ask some other ConnectionService
to create a RemoteConference
given an outgoing request. This is used by ConnectionService
s 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 . |
Return | |
---|---|
RemoteConference? |
The RemoteConference object to satisfy this call, or null to not handle the call. |
createRemoteOutgoingConnection
fun createRemoteOutgoingConnection(
connectionManagerPhoneAccount: PhoneAccountHandle,
request: ConnectionRequest
): RemoteConnection?
Ask some other ConnectionService
to create a RemoteConnection
given an outgoing request. This is used by ConnectionService
s 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 . |
Return | |
---|---|
RemoteConnection? |
The Connection object to satisfy this call, or null to not handle the call. |
getAllConferences
fun getAllConferences(): MutableCollection<Conference!>!
Returns all the active Conference
s for which this ConnectionService
has taken responsibility.
Return | |
---|---|
MutableCollection<Conference!>! |
A collection of Conference s created by this ConnectionService . |
getAllConnections
fun getAllConnections(): MutableCollection<Connection!>!
Returns all the active Connection
s for which this ConnectionService
has taken responsibility.
Return | |
---|---|
MutableCollection<Connection!>! |
A collection of Connection s created by this ConnectionService . |
onBind
fun onBind(intent: Intent!): IBinder?
Return the communication channel to the service. May return null if clients can not bind to the service. The returned android.os.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 android.content.Context#bindService. Note that any extras that were included with the Intent at that point will not be seen here. |
Return | |
---|---|
IBinder? |
Return an IBinder through which clients can call on to the service. |
onConference
open fun onConference(
connection1: Connection!,
connection2: Connection!
): Unit
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
.
Parameters | |
---|---|
connection1 |
Connection!: A connection to merge into a conference call. |
connection2 |
Connection!: A connection to merge into a conference call. |
onConnectionServiceFocusGained
open fun onConnectionServiceFocusGained(): Unit
Called when the ConnectionService
has gained the call focus. The ConnectionService
can acquire the call resources at this time.
onConnectionServiceFocusLost
open fun onConnectionServiceFocusLost(): Unit
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
open fun onCreateConferenceComplete(conference: Conference): Unit
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
open fun onCreateConnectionComplete(connection: Connection): Unit
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
open fun onCreateIncomingConference(
connectionManagerPhoneAccount: PhoneAccountHandle,
request: ConnectionRequest
): Conference?
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 . |
Return | |
---|---|
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
open fun onCreateIncomingConferenceFailed(
connectionManagerPhoneAccount: PhoneAccountHandle?,
request: ConnectionRequest?
): Unit
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
open fun onCreateIncomingConnection(
connectionManagerPhoneAccount: PhoneAccountHandle!,
request: ConnectionRequest!
): Connection!
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. |
Return | |
---|---|
Connection! |
The Connection object to satisfy this call, or null to not handle the call. |
onCreateIncomingConnectionFailed
open fun onCreateIncomingConnectionFailed(
connectionManagerPhoneAccount: PhoneAccountHandle!,
request: ConnectionRequest!
): Unit
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
open fun onCreateIncomingHandoverConnection(
fromPhoneAccountHandle: PhoneAccountHandle!,
request: ConnectionRequest!
): Connection!
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 android.telecom.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 android.telecom.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.
<code>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; } </code>
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. |
Return | |
---|---|
Connection! |
Connection instance corresponding to the handover call. |
onCreateOutgoingConference
open fun onCreateOutgoingConference(
connectionManagerPhoneAccount: PhoneAccountHandle,
request: ConnectionRequest
): Conference?
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 If this parameter is |
request |
ConnectionRequest: Details about the outgoing call. This value cannot be null . |
Return | |
---|---|
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
open fun onCreateOutgoingConferenceFailed(
connectionManagerPhoneAccount: PhoneAccountHandle,
request: ConnectionRequest
): Unit
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
open fun onCreateOutgoingConnection(
connectionManagerPhoneAccount: PhoneAccountHandle!,
request: ConnectionRequest!
): Connection!
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 If this parameter is |
request |
ConnectionRequest!: Details about the outgoing call. |
Return | |
---|---|
Connection! |
The Connection object to satisfy this call, or the result of an invocation of Connection.createFailedConnection(DisconnectCause) to not handle the call. |
onCreateOutgoingConnectionFailed
open fun onCreateOutgoingConnectionFailed(
connectionManagerPhoneAccount: PhoneAccountHandle!,
request: ConnectionRequest!
): Unit
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
open fun onCreateOutgoingHandoverConnection(
fromPhoneAccountHandle: PhoneAccountHandle!,
request: ConnectionRequest!
): Connection!
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 android.telecom.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 android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)
.
For a full discussion of the handover process and the APIs involved, see android.telecom.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.
<code>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; } </code>
Parameters | |
---|---|
fromPhoneAccountHandle |
PhoneAccountHandle!: PhoneAccountHandle associated with the ConnectionService which needs to handover the call. |
request |
ConnectionRequest!: Details about the call to handover. |
Return | |
---|---|
Connection! |
Connection instance corresponding to the handover call. |
onHandoverFailed
open fun onHandoverFailed(
request: ConnectionRequest!,
error: Int
): Unit
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 android.telecom.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 android.telecom.Call.Callback#HANDOVER_FAILURE_DEST_APP_REJECTED , android.telecom.Call.Callback#HANDOVER_FAILURE_NOT_SUPPORTED , android.telecom.Call.Callback#HANDOVER_FAILURE_USER_REJECTED , android.telecom.Call.Callback#HANDOVER_FAILURE_ONGOING_EMERGENCY_CALL , or android.telecom.Call.Callback#HANDOVER_FAILURE_UNKNOWN |
onRemoteConferenceAdded
open fun onRemoteConferenceAdded(conference: RemoteConference!): Unit
Indicates that a remote conference has been created for existing RemoteConnection
s. When this method is invoked, this ConnectionService
should create its own representation of the conference call and send it to telecom using addConference
.
This is only relevant to ConnectionService
s which are registered with PhoneAccount.CAPABILITY_CONNECTION_MANAGER
.
Parameters | |
---|---|
conference |
RemoteConference!: The remote conference call. |
onRemoteExistingConnectionAdded
open fun onRemoteExistingConnectionAdded(connection: RemoteConnection!): Unit
Called when an existing connection is added remotely.
Parameters | |
---|---|
connection |
RemoteConnection!: The existing connection which was added. |
onUnbind
open fun onUnbind(intent: Intent!): Boolean
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 android.content.Context#bindService. Note that any extras that were included with the Intent at that point will not be seen here. |
Return | |
---|---|
Boolean |
Return true if you would like to have the service's onRebind method later called when new clients bind to it. |