am a79cf3c1: am 58ef48cb: Merge "Even, Even more telecom javadoc." into lmp-mr1-dev

* commit 'a79cf3c12dc0acb1d489457cd6b79f4899fa5491':
  Even, Even more telecom javadoc.

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) {}
 
     /**