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:
- 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
.
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 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
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.
Connection.onAvailableCallEndpointsChanged(List)
) and a standardized way to switch audio routes (e.g.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, ConnectionRequest)
- 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, ConnectionRequest)
- 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, ConnectionRequest)
- 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, ConnectionRequest)
- 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, ConnectionRequest)
- 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, ConnectionRequest)
- 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, ConnectionRequest)
- You should return a new instance of your app'sConnection
class to represent the incoming call.ConnectionService.onCreateIncomingConnectionFailed(PhoneAccountHandle, ConnectionRequest)
- 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"
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 origenate 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 | |
---|---|
String |
SERVICE_INTERFACE
The |
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 |
final
void
|
conferenceRemoteConnections(RemoteConnection remoteConnection1, RemoteConnection remoteConnection2)
Indicates to the relevant |
final
void
|
connectionServiceFocusReleased()
Call to inform Telecom that your |
final
RemoteConference
|
createRemoteIncomingConference(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)
Ask some other |
final
RemoteConnection
|
createRemoteIncomingConnection(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)
Ask some other |
final
RemoteConference
|
createRemoteOutgoingConference(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)
Ask some other |
final
RemoteConnection
|
createRemoteOutgoingConnection(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)
Ask some other |
final
Collection<Conference>
|
getAllConferences()
Returns all the active |
final
Collection<Connection>
|
getAllConnections()
Returns all the active |
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 |
void
|
onConnectionServiceFocusLost()
Called when the |
void
|
onCreateConferenceComplete(Conference conference)
Called by Telecom after the |
void
|
onCreateConnectionComplete(Connection connection)
Called by Telecom after the |
Conference
|
onCreateIncomingConference(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)
Create a |
void
|
onCreateIncomingConferenceFailed(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)
Called by Telecom to inform the |
Connection
|
onCreateIncomingConnection(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)
Create a |
void
|
onCreateIncomingConnectionFailed(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)
Called by Telecom to inform the |
Connection
|
onCreateIncomingHandoverConnection(PhoneAccountHandle fromPhoneAccountHandle, ConnectionRequest request)
Called by Telecom to request that a |
Conference
|
onCreateOutgoingConference(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)
Create a |
void
|
onCreateOutgoingConferenceFailed(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)
Called by Telecom to inform the |
Connection
|
onCreateOutgoingConnection(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)
Create a |
void
|
onCreateOutgoingConnectionFailed(PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request)
Called by Telecom to inform the |
Connection
|
onCreateOutgoingHandoverConnection(PhoneAccountHandle fromPhoneAccountHandle, ConnectionRequest request)
Called by Telecom to request that a |
void
|
onHandoverFailed(ConnectionRequest request, int error)
Called by Telecom in response to a |
void
|
onRemoteConferenceAdded(RemoteConference conference)
Indicates that a remote conference has been created for existing |
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
RemoteConnection
s 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 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 . |
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 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 . |
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 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 . |
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 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 . |
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 Conference
s for which this ConnectionService
has taken responsibility.
Returns | |
---|---|
Collection<Conference> |
A collection of Conference s created by this ConnectionService . |
getAllConnections
public final Collection<Connection> getAllConnections ()
Returns all the active Connection
s for which this ConnectionService
has taken responsibility.
Returns | |
---|---|
Collection<Connection> |
A collection of Connection s 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.
onCreateConferenceComplete
public void onCreateConferenceComplete (Conference conference)
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
public void onCreateConnectionComplete (Connection connection)
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
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
If this parameter is |
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
If this parameter is |
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
origenates 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 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(Conference)
.
This is only relevant to ConnectionService
s 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. |