Telecom API updates (1/6)

Bug: 18292176

Change-Id: I060366234a5a60510c385dc837f2b7e79596eaf5

telecomm/java/android/telecom/RemoteConnection.java

@@ -73,14 +73,21 @@ public final class RemoteConnection {
          */
         public void onRingbackRequested(RemoteConnection connection, boolean ringback) {}
 
+        /** @hide */
+        @Deprecated public void onCallCapabilitiesChanged(
+                RemoteConnection connection,
+                int callCapabilities) {}
+
         /**
          * Indicates that the call capabilities of this {@code RemoteConnection} have changed.
-         * See {@link #getCallCapabilities()}.
+         * See {@link #getConnectionCapabilities()}.
          *
          * @param connection The {@code RemoteConnection} invoking this method.
-         * @param callCapabilities The new call capabilities of the {@code RemoteConnection}.
+         * @param connectionCapabilities The new capabilities of the {@code RemoteConnection}.
          */
-        public void onCallCapabilitiesChanged(RemoteConnection connection, int callCapabilities) {}
+        public void onConnectionCapabilitiesChanged(
+                RemoteConnection connection,
+                int connectionCapabilities) {}
 
         /**
          * Invoked when the post-dial sequence in the outgoing {@code Connection} has reached a
@@ -385,7 +392,7 @@ public final class RemoteConnection {
     private DisconnectCause mDisconnectCause;
     private boolean mRingbackRequested;
     private boolean mConnected;
-    private int mCallCapabilities;
+    private int mConnectionCapabilities;
     private int mVideoState;
     private VideoProvider mVideoProvider;
     private boolean mIsVoipAudioMode;
@@ -420,7 +427,7 @@ public final class RemoteConnection {
         mState = connection.getState();
         mDisconnectCause = connection.getDisconnectCause();
         mRingbackRequested = connection.isRingbackRequested();
-        mCallCapabilities = connection.getCapabilities();
+        mConnectionCapabilities = connection.getConnectionCapabilities();
         mVideoState = connection.getVideoState();
         mVideoProvider = new RemoteConnection.VideoProvider(connection.getVideoProvider());
         mIsVoipAudioMode = connection.getIsVoipAudioMode();
@@ -477,23 +484,29 @@ public final class RemoteConnection {
     }
 
     /**
+     * Obtains the reason why this {@code RemoteConnection} may have been disconnected.
+     *
      * @return For a {@link Connection#STATE_DISCONNECTED} {@code RemoteConnection}, the
-     * disconnect cause expressed as a code chosen from among those declared in
-     * {@link DisconnectCause}.
+     *         disconnect cause expressed as a code chosen from among those declared in
+     *         {@link DisconnectCause}.
      */
     public DisconnectCause getDisconnectCause() {
         return mDisconnectCause;
     }
 
     /**
+     * Obtains the capabilities of this {@code RemoteConnection}.
+     *
      * @return A bitmask of the capabilities of the {@code RemoteConnection}, as defined in
-     *         {@link PhoneCapabilities}.
+     *         the {@code CAPABILITY_*} constants in class {@link Connection}.
      */
-    public int getCallCapabilities() {
-        return mCallCapabilities;
+    public int getConnectionCapabilities() {
+        return mConnectionCapabilities;
     }
 
     /**
+     * Determines if the audio mode of this {@code RemoteConnection} is VOIP.
+     *
      * @return {@code true} if the {@code RemoteConnection}'s current audio mode is VOIP.
      */
     public boolean isVoipAudioMode() {
@@ -501,30 +514,38 @@ public final class RemoteConnection {
     }
 
     /**
+     * Obtains status hints pertaining to this {@code RemoteConnection}.
+     *
      * @return The current {@link StatusHints} of this {@code RemoteConnection},
-     * or {@code null} if none have been set.
+     *         or {@code null} if none have been set.
      */
     public StatusHints getStatusHints() {
         return mStatusHints;
     }
 
     /**
-     * @return The address (e.g., phone number) to which the {@code RemoteConnection} is currently
-     * connected.
+     * Obtains the address of this {@code RemoteConnection}.
+     *
+     * @return The address (e.g., phone number) to which the {@code RemoteConnection}
+     *         is currently connected.
      */
     public Uri getAddress() {
         return mAddress;
     }
 
     /**
-     * @return The presentation requirements for the address. See {@link TelecomManager} for valid
-     * values.
+     * Obtains the presentation requirements for the address of this {@code RemoteConnection}.
+     *
+     * @return The presentation requirements for the address. See
+     *         {@link TelecomManager} for valid values.
      */
     public int getAddressPresentation() {
         return mAddressPresentation;
     }
 
     /**
+     * Obtains the display name for this {@code RemoteConnection}'s caller.
+     *
      * @return The display name for the caller.
      */
     public CharSequence getCallerDisplayName() {
@@ -532,16 +553,20 @@ public final class RemoteConnection {
     }
 
     /**
+     * Obtains the presentation requirements for this {@code RemoteConnection}'s
+     * caller's display name.
+     *
      * @return The presentation requirements for the caller display name. See
-     * {@link TelecomManager} for valid values.
+     *         {@link TelecomManager} for valid values.
      */
     public int getCallerDisplayNamePresentation() {
         return mCallerDisplayNamePresentation;
     }
 
     /**
-     * @return The video state of the {@code RemoteConnection}. See
-     * {@link VideoProfile.VideoState}.
+     * Obtains the video state of this {@code RemoteConnection}.
+     *
+     * @return The video state of the {@code RemoteConnection}. See {@link VideoProfile.VideoState}.
      * @hide
      */
     public int getVideoState() {
@@ -549,6 +574,8 @@ public final class RemoteConnection {
     }
 
     /**
+     * Obtains the video provider of this {@code RemoteConnection}.
+     *
      * @return The video provider associated with this {@code RemoteConnection}.
      * @hide
      */
@@ -557,8 +584,10 @@ public final class RemoteConnection {
     }
 
     /**
+     * Determines whether this {@code RemoteConnection} is requesting ringback.
+     *
      * @return Whether the {@code RemoteConnection} is requesting that the framework play a
-     * ringback tone on its behalf.
+     *         ringback tone on its behalf.
      */
     public boolean isRingbackRequested() {
         return false;
@@ -800,10 +829,11 @@ public final class RemoteConnection {
     /**
      * @hide
      */
-    void setCallCapabilities(int callCapabilities) {
-        mCallCapabilities = callCapabilities;
+    void setConnectionCapabilities(int connectionCapabilities) {
+        mConnectionCapabilities = connectionCapabilities;
         for (Callback c : mCallbacks) {
-            c.onCallCapabilitiesChanged(this, callCapabilities);
+            c.onConnectionCapabilitiesChanged(this, connectionCapabilities);
+            c.onCallCapabilitiesChanged(this, connectionCapabilities);
         }
     }