summaryrefslogtreecommitdiffstats
path: root/telecomm
diff options
context:
space:
mode:
authorSantos Cordon <santoscordon@google.com>2014-10-29 13:49:58 -0700
committerSantos Cordon <santoscordon@google.com>2014-10-31 15:28:46 -0700
commita663f86fd30c952a3b747763d2faea709eccbe91 (patch)
tree14ab7cf5a7da0ee078d243df268e21d6b623ad70 /telecomm
parent38b00a63c9f637bbe43b6ea3785c9577c43dbac5 (diff)
downloadframeworks_base-a663f86fd30c952a3b747763d2faea709eccbe91.zip
frameworks_base-a663f86fd30c952a3b747763d2faea709eccbe91.tar.gz
frameworks_base-a663f86fd30c952a3b747763d2faea709eccbe91.tar.bz2
Even, Even more telecom javadoc.
Bug: 18142177 Change-Id: Ic952f3a81cb957bc5b9b6d0aa755adaab9fb74aa
Diffstat (limited to 'telecomm')
-rw-r--r--telecomm/java/android/telecom/ConnectionService.java66
1 files changed, 58 insertions, 8 deletions
diff --git a/telecomm/java/android/telecom/ConnectionService.java b/telecomm/java/android/telecom/ConnectionService.java
index 6e41c33..4648d78 100644
--- a/telecomm/java/android/telecom/ConnectionService.java
+++ b/telecomm/java/android/telecom/ConnectionService.java
@@ -40,8 +40,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>
+ * &lt;service android:name="com.example.package.MyConnectionService"
+ * android:label="@string/some_label_for_my_connection_service"
+ * android:permission="android.permission.BIND_CONNECTION_SERVICE"&gt;
+ * &lt;intent-filter&gt;
+ * &lt;action android:name="android.telecom.ConnectionService" /&gt;
+ * &lt;/intent-filter&gt;
+ * &lt;/service&gt;
+ * </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}.
*/
public abstract class ConnectionService extends Service {
/**
@@ -746,7 +775,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)}.
@@ -763,7 +794,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)}.
@@ -779,12 +812,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);
}
/**
@@ -937,6 +977,16 @@ 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) {}
/**