Merge \"API cleanups per API review.\" into nyc-mr1-dev

am: 138a3f3ad4 Change-Id: Iad4f2bdc3f903a6497f97ccd2fbdc1943ebded94
2016-06-29 23:49:07 +00:00
parent 8ca3333d90 138a3f3ad4
commit ba5f1622da
6 changed files with 167 additions and 37 deletions
--- a/api/current.txt
+++ b/api/current.txt
@@ -36218,7 +36218,7 @@ package android.telecom {
    method public final void setConnectionTime(long);
    method public final void setDialing();
    method public final void setDisconnected(android.telecom.DisconnectCause);
-    method public final deprecated void setExtras(android.os.Bundle);
+    method public final void setExtras(android.os.Bundle);
    method public final void setOnHold();
    method public final void setStatusHints(android.telecom.StatusHints);
    method public final void setVideoProvider(android.telecom.Connection, android.telecom.Connection.VideoProvider);
@@ -36283,7 +36283,7 @@ package android.telecom {
    method public final void setConnectionProperties(int);
    method public final void setDialing();
    method public final void setDisconnected(android.telecom.DisconnectCause);
-    method public final deprecated void setExtras(android.os.Bundle);
+    method public final void setExtras(android.os.Bundle);
    method public final void setInitialized();
    method public final void setInitializing();
    method public final void setNextPostDialChar(char);
--- a/api/system-current.txt
+++ b/api/system-current.txt
@@ -39066,7 +39066,7 @@ package android.telecom {
    method public final void setConnectionTime(long);
    method public final void setDialing();
    method public final void setDisconnected(android.telecom.DisconnectCause);
-    method public final deprecated void setExtras(android.os.Bundle);
+    method public final void setExtras(android.os.Bundle);
    method public final void setOnHold();
    method public final void setStatusHints(android.telecom.StatusHints);
    method public final void setVideoProvider(android.telecom.Connection, android.telecom.Connection.VideoProvider);
@@ -39133,7 +39133,7 @@ package android.telecom {
    method public final void setConnectionProperties(int);
    method public final void setDialing();
    method public final void setDisconnected(android.telecom.DisconnectCause);
-    method public final deprecated void setExtras(android.os.Bundle);
+    method public final void setExtras(android.os.Bundle);
    method public final void setInitialized();
    method public final void setInitializing();
    method public final void setNextPostDialChar(char);
--- a/api/test-current.txt
+++ b/api/test-current.txt
@@ -36296,7 +36296,7 @@ package android.telecom {
    method public final void setConnectionTime(long);
    method public final void setDialing();
    method public final void setDisconnected(android.telecom.DisconnectCause);
-    method public final deprecated void setExtras(android.os.Bundle);
+    method public final void setExtras(android.os.Bundle);
    method public final void setOnHold();
    method public final void setStatusHints(android.telecom.StatusHints);
    method public final void setVideoProvider(android.telecom.Connection, android.telecom.Connection.VideoProvider);
@@ -36361,7 +36361,7 @@ package android.telecom {
    method public final void setConnectionProperties(int);
    method public final void setDialing();
    method public final void setDisconnected(android.telecom.DisconnectCause);
-    method public final deprecated void setExtras(android.os.Bundle);
+    method public final void setExtras(android.os.Bundle);
    method public final void setInitialized();
    method public final void setInitializing();
    method public final void setNextPostDialChar(char);
--- a/telecomm/java/android/telecom/Call.java
+++ b/telecomm/java/android/telecom/Call.java
@@ -701,6 +701,24 @@ public final class Call {
        }
    }

+    /**
+     * Defines callbacks which inform the {@link InCallService} of changes to a {@link Call}.
+     * These callbacks can originate from the Telecom framework, or a {@link ConnectionService}
+     * implementation.
+     * <p>
+     * You can handle these callbacks by extending the {@link Callback} class and overriding the
+     * callbacks that your {@link InCallService} is interested in.  The callback methods include the
+     * {@link Call} for which the callback applies, allowing reuse of a single instance of your
+     * {@link Callback} implementation, if desired.
+     * <p>
+     * Use {@link Call#registerCallback(Callback)} to register your callback(s).  Ensure
+     * {@link Call#unregisterCallback(Callback)} is called when you no longer require callbacks
+     * (typically in {@link InCallService#onCallRemoved(Call)}).
+     * Note: Callbacks which occur before you call {@link Call#registerCallback(Callback)} will not
+     * reach your implementation of {@link Callback}, so it is important to register your callback
+     * as soon as your {@link InCallService} is notified of a new call via
+     * {@link InCallService#onCallAdded(Call)}.
+     */
    public static abstract class Callback {
        /**
         * Invoked when the state of this {@code Call} has changed. See {@link #getState()}.
@@ -785,7 +803,13 @@ public final class Call {
        public void onConferenceableCallsChanged(Call call, List<Call> conferenceableCalls) {}

        /**
-         * Invoked when a call receives an event from its associated {@link Connection}.
+         * Invoked when a {@link Call} receives an event from its associated {@link Connection}.
+         * <p>
+         * Where possible, the Call should make an attempt to handle {@link Connection} events which
+         * are part of the {@code android.telecom.*} namespace.  The Call should ignore any events
+         * it does not wish to handle.  Unexpected events should be handled gracefully, as it is
+         * possible that a {@link ConnectionService} has defined its own Connection events which a
+         * Call is not aware of.
         * <p>
         * See {@link Connection#sendConnectionEvent(String, Bundle)}.
         *
@@ -984,11 +1008,32 @@ public final class Call {
     * Sends a {@code Call} event from this {@code Call} to the associated {@link Connection} in
     * the {@link ConnectionService}.
     * <p>
+     * Call events are used to communicate point in time information from an {@link InCallService}
+     * to a {@link ConnectionService}.  A {@link ConnectionService} implementation could define
+     * events which enable the {@link InCallService}, for example, toggle a unique feature of the
+     * {@link ConnectionService}.
+     * <p>
+     * A {@link ConnectionService} can communicate to the {@link InCallService} using
+     * {@link Connection#sendConnectionEvent(String, Bundle)}.
+     * <p>
     * Events are exposed to {@link ConnectionService} implementations via
     * {@link android.telecom.Connection#onCallEvent(String, Bundle)}.
     * <p>
     * No assumptions should be made as to how a {@link ConnectionService} will handle these events.
-     * Events should be fully qualified (e.g., com.example.event.MY_EVENT) to avoid conflicts.
+     * The {@link InCallService} must assume that the {@link ConnectionService} could chose to
+     * ignore some events altogether.
+     * <p>
+     * Events should be fully qualified (e.g., {@code com.example.event.MY_EVENT}) to avoid
+     * conflicts between {@link InCallService} implementations.  Further, {@link InCallService}
+     * implementations shall not re-purpose events in the {@code android.*} namespace, nor shall
+     * they define their own event types in this namespace.  When defining a custom event type,
+     * ensure the contents of the extras {@link Bundle} is clearly defined.  Extra keys for this
+     * bundle should be named similar to the event type (e.g. {@code com.example.extra.MY_EXTRA}).
+     * <p>
+     * When defining events and the associated extras, it is important to keep their behavior
+     * consistent when the associated {@link InCallService} is updated.  Support for deprecated
+     * events/extras should me maintained to ensure backwards compatibility with older
+     * {@link ConnectionService} implementations which were built to support the older behavior.
     *
     * @param event The connection event.
     * @param extras Bundle containing extra information associated with the event.
--- a/telecomm/java/android/telecom/Conference.java
+++ b/telecomm/java/android/telecom/Conference.java
@@ -256,60 +256,63 @@ public abstract class Conference extends Conferenceable {
    }

    /**
-     * Invoked when the Conference and all it's {@link Connection}s should be disconnected.
+     * Notifies the {@link Conference} when the Conference and all it's {@link Connection}s should
+     * be disconnected.
     */
    public void onDisconnect() {}

    /**
-     * Invoked when the specified {@link Connection} should be separated from the conference call.
+     * Notifies the {@link Conference} when the specified {@link Connection} should be separated
+     * from the conference call.
     *
     * @param connection The connection to separate.
     */
    public void onSeparate(Connection connection) {}

    /**
-     * Invoked when the specified {@link Connection} should merged with the conference call.
+     * Notifies the {@link Conference} when the specified {@link Connection} should merged with the
+     * conference call.
     *
     * @param connection The {@code Connection} to merge.
     */
    public void onMerge(Connection connection) {}

    /**
-     * Invoked when the conference should be put on hold.
+     * Notifies the {@link Conference} when it should be put on hold.
     */
    public void onHold() {}

    /**
-     * Invoked when the conference should be moved from hold to active.
+     * Notifies the {@link Conference} when it should be moved from a held to active state.
     */
    public void onUnhold() {}

    /**
-     * Invoked when the child calls should be merged. Only invoked if the conference contains the
-     * capability {@link Connection#CAPABILITY_MERGE_CONFERENCE}.
+     * Notifies the {@link Conference} when the child calls should be merged.  Only invoked if the
+     * conference contains the capability {@link Connection#CAPABILITY_MERGE_CONFERENCE}.
     */
    public void onMerge() {}

    /**
-     * Invoked when the child calls should be swapped. Only invoked if the conference contains the
-     * capability {@link Connection#CAPABILITY_SWAP_CONFERENCE}.
+     * Notifies the {@link Conference} when the child calls should be swapped. Only invoked if the
+     * conference contains the capability {@link Connection#CAPABILITY_SWAP_CONFERENCE}.
     */
    public void onSwap() {}

    /**
-     * Notifies this conference of a request to play a DTMF tone.
+     * Notifies the {@link Conference} of a request to play a DTMF tone.
     *
     * @param c A DTMF character.
     */
    public void onPlayDtmfTone(char c) {}

    /**
-     * Notifies this conference of a request to stop any currently playing DTMF tones.
+     * Notifies the {@link Conference} of a request to stop any currently playing DTMF tones.
     */
    public void onStopDtmfTone() {}

    /**
-     * Notifies this conference that the {@link #getAudioState()} property has a new value.
+     * Notifies the {@link Conference} that the {@link #getAudioState()} property has a new value.
     *
     * @param state The new call audio state.
     * @deprecated Use {@link #onCallAudioStateChanged(CallAudioState)} instead.
@@ -320,14 +323,15 @@ public abstract class Conference extends Conferenceable {
    public void onAudioStateChanged(AudioState state) {}

    /**
-     * Notifies this conference that the {@link #getCallAudioState()} property has a new value.
+     * Notifies the {@link Conference} that the {@link #getCallAudioState()} property has a new
+     * value.
     *
     * @param state The new call audio state.
     */
    public void onCallAudioStateChanged(CallAudioState state) {}

    /**
-     * Notifies this conference that a connection has been added to it.
+     * Notifies the {@link Conference} that a {@link Connection} has been added to it.
     *
     * @param connection The newly added connection.
     */
@@ -680,12 +684,13 @@ public abstract class Conference extends Conferenceable {
     * New or existing keys are replaced in the {@code Conference} extras.  Keys which are no longer
     * in the new extras, but were present the last time {@code setExtras} was called are removed.
     * <p>
+     * Alternatively you may use the {@link #putExtras(Bundle)}, and
+     * {@link #removeExtras(String...)} methods to modify the extras.
+     * <p>
     * No assumptions should be made as to how an In-Call UI or service will handle these extras.
-     * Keys should be fully qualified (e.g., com.example.MY_EXTRA) to avoid conflicts.
+     * Keys should be fully qualified (e.g., com.example.extras.MY_EXTRA) to avoid conflicts.
     *
     * @param extras The extras associated with this {@code Conference}.
-     * @deprecated Use {@link #putExtras(Bundle)} to add extras.  Use {@link #removeExtras(List)}
-     * to remove extras.
     */
    public final void setExtras(@Nullable Bundle extras) {
        // Keeping putExtras and removeExtras in the same lock so that this operation happens as a
--- a/telecomm/java/android/telecom/Connection.java
+++ b/telecomm/java/android/telecom/Connection.java
@@ -53,6 +53,37 @@ import java.util.concurrent.ConcurrentHashMap;
 * Implementations are then responsible for updating the state of the {@code Connection}, and
 * must call {@link #destroy()} to signal to the framework that the {@code Connection} is no
 * longer used and associated resources may be recovered.
+ * <p>
+ * Subclasses of {@code Connection} override the {@code on*} methods to provide the the
+ * {@link ConnectionService}'s implementation of calling functionality.  The {@code on*} methods are
+ * called by Telecom to inform an instance of a {@code Connection} of actions specific to that
+ * {@code Connection} instance.
+ * <p>
+ * Basic call support requires overriding the following methods: {@link #onAnswer()},
+ * {@link #onDisconnect()}, {@link #onReject()}, {@link #onAbort()}
+ * <p>
+ * Where a {@code Connection} has {@link #CAPABILITY_SUPPORT_HOLD}, the {@link #onHold()} and
+ * {@link #onUnhold()} methods should be overridden to provide hold support for the
+ * {@code Connection}.
+ * <p>
+ * Where a {@code Connection} supports a variation of video calling (e.g. the
+ * {@code CAPABILITY_SUPPORTS_VT_*} capability bits), {@link #onAnswer(int)} should be overridden
+ * to support answering a call as a video call.
+ * <p>
+ * Where a {@code Connection} has {@link #PROPERTY_IS_EXTERNAL_CALL} and
+ * {@link #CAPABILITY_CAN_PULL_CALL}, {@link #onPullExternalCall()} should be overridden to provide
+ * support for pulling the external call.
+ * <p>
+ * Where a {@code Connection} supports conference calling {@link #onSeparate()} should be
+ * overridden.
+ * <p>
+ * There are a number of other {@code on*} methods which a {@code Connection} can choose to
+ * implement, depending on whether it is concerned with the associated calls from Telecom.  If,
+ * for example, call events from a {@link InCallService} are handled,
+ * {@link #onCallEvent(String, Bundle)} should be overridden.  Another example is
+ * {@link #onExtrasChanged(Bundle)}, which should be overridden if the {@code Connection} wishes to
+ * make use of extra information provided via the {@link Call#putExtras(Bundle)} and
+ * {@link Call#removeExtras(String...)} methods.
 */
 public abstract class Connection extends Conferenceable {

@@ -385,7 +416,7 @@ public abstract class Connection extends Conferenceable {
    /**
     * Connection event used to inform Telecom that it should play the on hold tone.  This is used
     * to play a tone when the peer puts the current call on hold.  Sent to Telecom via
-     * {@link #sendConnectionEvent(String)}.
+     * {@link #sendConnectionEvent(String, Bundle)}.
     * @hide
     */
    public static final String EVENT_ON_HOLD_TONE_START =
@@ -394,7 +425,7 @@ public abstract class Connection extends Conferenceable {
    /**
     * Connection event used to inform Telecom that it should stop the on hold tone.  This is used
     * to stop a tone when the peer puts the current call on hold.  Sent to Telecom via
-     * {@link #sendConnectionEvent(String)}.
+     * {@link #sendConnectionEvent(String, Bundle)}.
     * @hide
     */
    public static final String EVENT_ON_HOLD_TONE_END =
@@ -409,12 +440,18 @@ public abstract class Connection extends Conferenceable {
     * {@link Call.Details#PROPERTY_IS_EXTERNAL_CALL} and
     * {@link Call.Details#CAPABILITY_CAN_PULL_CALL}, but the {@link ConnectionService} could not
     * pull the external call due to an error condition.
+     * <p>
+     * Sent via {@link #sendConnectionEvent(String, Bundle)}.  The {@link Bundle} parameter is
+     * expected to be null when this connection event is used.
     */
    public static final String EVENT_CALL_PULL_FAILED = "android.telecom.event.CALL_PULL_FAILED";

    /**
     * Connection event used to inform {@link InCallService}s when the merging of two calls has
     * failed. The User Interface should use this message to inform the user of the error.
+     * <p>
+     * Sent via {@link #sendConnectionEvent(String, Bundle)}.  The {@link Bundle} parameter is
+     * expected to be null when this connection event is used.
     */
    public static final String EVENT_CALL_MERGE_FAILED = "android.telecom.event.CALL_MERGE_FAILED";

@@ -464,7 +501,12 @@ public abstract class Connection extends Conferenceable {
        mConnectionCapabilities |= capability;
    }

-
+    /**
+     * Renders a set of capability bits ({@code CAPABILITY_*}) as a human readable string.
+     *
+     * @param capabilities A capability bit field.
+     * @return A human readable string representation.
+     */
    public static String capabilitiesToString(int capabilities) {
        StringBuilder builder = new StringBuilder();
        builder.append("[Capabilities:");
@@ -533,6 +575,12 @@ public abstract class Connection extends Conferenceable {
        return builder.toString();
    }

+    /**
+     * Renders a set of property bits ({@code PROPERTY_*}) as a human readable string.
+     *
+     * @param properties A property bit field.
+     * @return A human readable string representation.
+     */
    public static String propertiesToString(int properties) {
        StringBuilder builder = new StringBuilder();
        builder.append("[Properties:");
@@ -1909,12 +1957,13 @@ public abstract class Connection extends Conferenceable {
     * New or existing keys are replaced in the {@code Connection} extras.  Keys which are no longer
     * in the new extras, but were present the last time {@code setExtras} was called are removed.
     * <p>
+     * Alternatively you may use the {@link #putExtras(Bundle)}, and
+     * {@link #removeExtras(String...)} methods to modify the extras.
+     * <p>
     * No assumptions should be made as to how an In-Call UI or service will handle these extras.
     * Keys should be fully qualified (e.g., com.example.MY_EXTRA) to avoid conflicts.
     *
     * @param extras The extras associated with this {@code Connection}.
-     * @deprecated Use {@link #putExtras(Bundle)} to add extras.  Use {@link #removeExtras(List)}
-     * to remove extras.
     */
    public final void setExtras(@Nullable Bundle extras) {
        checkImmutable();
@@ -2175,6 +2224,12 @@ public abstract class Connection extends Conferenceable {
     * <p>
     * The {@link InCallService} issues a Call event via {@link Call#sendCallEvent(String, Bundle)}.
     * <p>
+     * Where possible, the Connection should make an attempt to handle {@link Call} events which
+     * are part of the {@code android.telecom.*} namespace.  The Connection should ignore any events
+     * it does not wish to handle.  Unexpected events should be handled gracefully, as it is
+     * possible that a {@link InCallService} has defined its own Call events which a Connection is
+     * not aware of.
+     * <p>
     * See also {@link Call#sendCallEvent(String, Bundle)}.
     *
     * @param event The call event.
@@ -2378,16 +2433,41 @@ public abstract class Connection extends Conferenceable {
    }

    /**
-     * Sends an event associated with this {@code Connection}, with associated event extras.
-     *
-     * Events are exposed to {@link InCallService} implementations via the
-     * {@link Call.Callback#onConnectionEvent(Call, String, Bundle)} API.
-     *
+     * Sends an event associated with this {@code Connection} with associated event extras to the
+     * {@link InCallService}.
+     * <p>
+     * Connection events are used to communicate point in time information from a
+     * {@link ConnectionService} to a {@link InCallService} implementations.  An example of a
+     * custom connection event includes notifying the UI when a WIFI call has been handed over to
+     * LTE, which the InCall UI might use to inform the user that billing charges may apply.  The
+     * Android Telephony framework will send the {@link #EVENT_CALL_MERGE_FAILED} connection event
+     * when a call to {@link Call#mergeConference()} has failed to complete successfully.  A
+     * connection event could also be used to trigger UI in the {@link InCallService} which prompts
+     * the user to make a choice (e.g. whether they want to incur roaming costs for making a call),
+     * which is communicated back via {@link Call#sendCallEvent(String, Bundle)}.
+     * <p>
+     * Events are exposed to {@link InCallService} implementations via
+     * {@link Call.Callback#onConnectionEvent(Call, String, Bundle)}.
+     * <p>
     * No assumptions should be made as to how an In-Call UI or service will handle these events.
-     * Events should be fully qualified (e.g., com.example.event.MY_EVENT) to avoid conflicts.
+     * The {@link ConnectionService} must assume that the In-Call UI could even chose to ignore
+     * some events altogether.
+     * <p>
+     * Events should be fully qualified (e.g. {@code com.example.event.MY_EVENT}) to avoid
+     * conflicts between {@link ConnectionService} implementations.  Further, custom
+     * {@link ConnectionService} implementations shall not re-purpose events in the
+     * {@code android.*} namespace, nor shall they define new event types in this namespace.  When
+     * defining a custom event type, ensure the contents of the extras {@link Bundle} is clearly
+     * defined.  Extra keys for this bundle should be named similar to the event type (e.g.
+     * {@code com.example.extra.MY_EXTRA}).
+     * <p>
+     *  When defining events and the associated extras, it is important to keep their behavior
+     * consistent when the associated {@link ConnectionService} is updated.  Support for deprecated
+     * events/extras should me maintained to ensure backwards compatibility with older
+     * {@link InCallService} implementations which were built to support the older behavior.
     *
     * @param event The connection event.
-     * @param extras Bundle containing extra information associated with the event.
+     * @param extras Optional bundle containing extra information associated with the event.
     */
    public void sendConnectionEvent(String event, Bundle extras) {
        for (Listener l : mListeners) {