diff options
Diffstat (limited to 'telecomm/java/android/telecom/ConnectionService.java')
| -rw-r--r-- | telecomm/java/android/telecom/ConnectionService.java | 128 |
1 files changed, 118 insertions, 10 deletions
diff --git a/telecomm/java/android/telecom/ConnectionService.java b/telecomm/java/android/telecom/ConnectionService.java index 6eee99d..48e6ff3 100644 --- a/telecomm/java/android/telecom/ConnectionService.java +++ b/telecomm/java/android/telecom/ConnectionService.java @@ -16,8 +16,8 @@ package android.telecom; -import android.annotation.SystemApi; import android.annotation.SdkConstant; +import android.annotation.SystemApi; import android.app.Service; import android.content.ComponentName; import android.content.Intent; @@ -41,8 +41,37 @@ import java.util.UUID; import java.util.concurrent.ConcurrentHashMap; /** - * A {@link android.app.Service} that provides telephone connections to processes running on an - * Android device. + * {@code ConnectionService} is an abstract service that should be implemented by any app which can + * make phone calls and want those calls to be integrated into the built-in phone app. + * Once implemented, the {@code ConnectionService} needs two additional steps before it will be + * integrated into the phone app: + * <p> + * 1. <i>Registration in AndroidManifest.xml</i> + * <br/> + * <pre> + * <service android:name="com.example.package.MyConnectionService" + * android:label="@string/some_label_for_my_connection_service" + * android:permission="android.permission.BIND_CONNECTION_SERVICE"> + * <intent-filter> + * <action android:name="android.telecom.ConnectionService" /> + * </intent-filter> + * </service> + * </pre> + * <p> + * 2. <i> Registration of {@link PhoneAccount} with {@link TelecomManager}.</i> + * <br/> + * See {@link PhoneAccount} and {@link TelecomManager#registerPhoneAccount} for more information. + * <p> + * Once registered and enabled by the user in the dialer settings, telecom will bind to a + * {@code ConnectionService} implementation when it wants that {@code ConnectionService} to place + * a call or the service has indicated that is has an incoming call through + * {@link TelecomManager#addNewIncomingCall}. The {@code ConnectionService} can then expect a call + * to {@link #onCreateIncomingConnection} or {@link #onCreateOutgoingConnection} wherein it + * should provide a new instance of a {@link Connection} object. It is through this + * {@link Connection} object that telecom receives state updates and the {@code ConnectionService} + * receives call-commands such as answer, reject, hold and disconnect. + * <p> + * When there are no more live calls, telecom will unbind from the {@code ConnectionService}. * @hide */ @SystemApi @@ -749,7 +778,9 @@ public abstract class ConnectionService extends Service { /** * Ask some other {@code ConnectionService} to create a {@code RemoteConnection} given an - * incoming request. This is used to attach to existing incoming calls. + * incoming request. This is used by {@code ConnectionService}s that are registered with + * {@link PhoneAccount#CAPABILITY_CONNECTION_MANAGER} and want to be able to manage + * SIM-based incoming calls. * * @param connectionManagerPhoneAccount See description at * {@link #onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)}. @@ -766,7 +797,9 @@ public abstract class ConnectionService extends Service { /** * Ask some other {@code ConnectionService} to create a {@code RemoteConnection} given an - * outgoing request. This is used to initiate new outgoing calls. + * outgoing request. This is used by {@code ConnectionService}s that are registered with + * {@link PhoneAccount#CAPABILITY_CONNECTION_MANAGER} and want to be able to use the + * SIM-based {@code ConnectionService} to place its outgoing calls. * * @param connectionManagerPhoneAccount See description at * {@link #onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)}. @@ -782,12 +815,19 @@ public abstract class ConnectionService extends Service { } /** - * Adds two {@code RemoteConnection}s to some {@code RemoteConference}. + * Indicates to the relevant {@code RemoteConnectionService} that the specified + * {@link RemoteConnection}s should be merged into a conference call. + * <p> + * If the conference request is successful, the method {@link #onRemoteConferenceAdded} will + * be invoked. + * + * @param remoteConnection1 The first of the remote connections to conference. + * @param remoteConnection2 The second of the remote connections to conference. */ public final void conferenceRemoteConnections( - RemoteConnection a, - RemoteConnection b) { - mRemoteConnectionManager.conferenceRemoteConnections(a, b); + RemoteConnection remoteConnection1, + RemoteConnection remoteConnection2) { + mRemoteConnectionManager.conferenceRemoteConnections(remoteConnection1, remoteConnection2); } /** @@ -825,6 +865,40 @@ public abstract class ConnectionService extends Service { } /** + * Adds a connection created by the {@link ConnectionService} and informs telecom of the new + * connection. + * + * @param phoneAccountHandle The phone account handle for the connection. + * @param connection The connection to add. + */ + public final void addExistingConnection(PhoneAccountHandle phoneAccountHandle, + Connection connection) { + + String id = addExistingConnectionInternal(connection); + if (id != null) { + List<String> emptyList = new ArrayList<>(0); + + ParcelableConnection parcelableConnection = new ParcelableConnection( + phoneAccountHandle, + connection.getState(), + connection.getCallCapabilities(), + connection.getAddress(), + connection.getAddressPresentation(), + connection.getCallerDisplayName(), + connection.getCallerDisplayNamePresentation(), + connection.getVideoProvider() == null ? + null : connection.getVideoProvider().getInterface(), + connection.getVideoState(), + connection.isRingbackRequested(), + connection.getAudioModeIsVoip(), + connection.getStatusHints(), + connection.getDisconnectCause(), + emptyList); + mAdapter.addExistingConnection(id, parcelableConnection); + } + } + + /** * Returns all the active {@code Connection}s for which this {@code ConnectionService} * has taken responsibility. * @@ -906,9 +980,25 @@ public abstract class ConnectionService extends Service { */ public void onConference(Connection connection1, Connection connection2) {} + /** + * Indicates that a remote conference has been created for existing {@link RemoteConnection}s. + * When this method is invoked, this {@link ConnectionService} should create its own + * representation of the conference call and send it to telecom using {@link #addConference}. + * <p> + * This is only relevant to {@link ConnectionService}s which are registered with + * {@link PhoneAccount#CAPABILITY_CONNECTION_MANAGER}. + * + * @param conference The remote conference call. + */ public void onRemoteConferenceAdded(RemoteConference conference) {} /** + * Called when an existing connection is added remotely. + * @param connection The existing connection which was added. + */ + public void onRemoteExistingConnectionAdded(RemoteConnection connection) {} + + /** * @hide */ public boolean containsConference(Conference conference) { @@ -920,6 +1010,11 @@ public abstract class ConnectionService extends Service { onRemoteConferenceAdded(remoteConference); } + /** {@hide} */ + void addRemoteExistingConnection(RemoteConnection remoteConnection) { + onRemoteExistingConnectionAdded(remoteConnection); + } + private void onAccountsInitialized() { mAreAccountsInitialized = true; for (Runnable r : mPreInitializationConnectionRequests) { @@ -928,6 +1023,18 @@ public abstract class ConnectionService extends Service { mPreInitializationConnectionRequests.clear(); } + /** + * Adds an existing connection to the list of connections, identified by a new UUID. + * + * @param connection The connection. + * @return The UUID of the connection (e.g. the call-id). + */ + private String addExistingConnectionInternal(Connection connection) { + String id = UUID.randomUUID().toString(); + addConnection(id, connection); + return id; + } + private void addConnection(String callId, Connection connection) { mConnectionById.put(callId, connection); mIdByConnection.put(connection, callId); @@ -935,7 +1042,8 @@ public abstract class ConnectionService extends Service { connection.setConnectionService(this); } - private void removeConnection(Connection connection) { + /** {@hide} */ + protected void removeConnection(Connection connection) { String id = mIdByConnection.get(connection); connection.unsetConnectionService(this); connection.removeConnectionListener(mConnectionListener); |