# Print output for @column tags ?>
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:
ConnectionService
.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 be granted the
appropriate permission before Telecom will bind to them.
Once registered and enabled by the user in the phone app settings or granted permission, telecom
will bind to a ConnectionService
implementation when it wants that
ConnectionService
to place a call or the service has indicated that is has an incoming
call through TelecomManager#addNewIncomingCall
. The ConnectionService
can then
expect a call to onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)
or onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)
wherein it should provide a new instance of a Connection
object. It is through this
Connection
object that telecom receives state updates and the ConnectionService
receives call-commands such as answer, reject, hold and disconnect.
When there are no more live calls, telecom will unbind from the ConnectionService
.
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
RemoteConnection
|
createRemoteIncomingConnection(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 |
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 |
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 | |
---|---|
public static final String SERVICE_INTERFACE
The Intent
that must be declared as handled by the service.
Constant Value: "android.telecom.ConnectionService"
public ConnectionService ()
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. |
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. |
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. |
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:
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) . |
request |
ConnectionRequest : Details about the incoming call. |
Returns | |
---|---|
RemoteConnection |
The Connection object to satisfy this call, or null to
not handle the call. |
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) . |
request |
ConnectionRequest : Details about the outgoing call. |
Returns | |
---|---|
RemoteConnection |
The Connection object to satisfy this call, or null to
not handle the call. |
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 . |
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 . |
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. |
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. |
public void onConnectionServiceFocusGained ()
Called when the ConnectionService
has gained the call focus. The
ConnectionService
can acquire the call resources at this time.
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.
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. |
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. |
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. |
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. |
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. |
public Connection onCreateOutgoingHandoverConnection (PhoneAccountHandle fromPhoneAccountHandle, ConnectionRequest request)
Called by Telecom to request that a ConnectionService
creates an instance of an
outgoing handover Connection
.
A call handover is the process where an ongoing call is transferred from one app (i.e.
ConnectionService
to another app. The user could, for example, choose to continue a
mobile network call in a video calling app. The mobile network call via the Telephony stack
is referred to as the source of the handover, and the video calling app is referred to as the
destination.
When considering a handover scenario the initiating device is where a user initiated
the handover process (e.g. by calling Call.handoverTo(PhoneAccountHandle, int, Bundle)
, and the other device is considered the receiving
device.
This method is called on the destination ConnectionService
on initiating
device when the user initiates a handover request from one app to another. The user request
originates in the InCallService
via
Call.handoverTo(PhoneAccountHandle, int, Bundle)
.
For a full discussion of the handover process and the APIs involved, see
Call.handoverTo(PhoneAccountHandle, int, Bundle)
.
Implementations of this method should return an instance of Connection
which
represents the handover. If your app does not wish to accept a handover to it at this time,
you can return null
. The code below shows an example of how this is done.
public Connection onCreateIncomingHandoverConnection(PhoneAccountHandle
fromPhoneAccountHandle, ConnectionRequest request) {
if (!isHandoverAvailable()) {
return null;
}
MyConnection connection = new MyConnection();
connection.setAddress(request.getAddress(), TelecomManager.PRESENTATION_ALLOWED);
connection.setVideoState(request.getVideoState());
return connection;
}
Parameters | |
---|---|
fromPhoneAccountHandle |
PhoneAccountHandle : PhoneAccountHandle associated with the
ConnectionService which needs to handover the call. |
request |
ConnectionRequest : Details about the call to handover. |
Returns | |
---|---|
Connection |
Connection instance corresponding to the handover call. |
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 |
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. |
public void onRemoteExistingConnectionAdded (RemoteConnection connection)
Called when an existing connection is added remotely.
Parameters | |
---|---|
connection |
RemoteConnection : The existing connection which was added. |
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. |