API cleanups per API review.

1. removing deprecation for setExtras on Connection/Conference as these have legitimate use-cases going forward. 2. Expanded documentation on Call.Callback class to clarify how it is expected to be used. 3. Updated Callback#onConnectionEvent callback docs to clarify its usage. 4. Expanded Call#sendCallEvent docs to clarify expected namespacing of call event keys and extras keys, as well as clarification about backwards compatibility and expectations of ConnectionServices. 5. Standardized the "invoked" vs "notifies" language in the Conference docs. 6. Clarified how Connection callbacks from Telecom should be implemented. 7. Added Bundle parameter expectations for pre-defined connection events. 8. Documented capabilities and properties toString methods. 9. Documented expectations for onCallEvent method. 10. Expanded documentation for sendConnectionEvent method to clarify namespacing, use cases, etc. Bug: 29759275 Bug: 29759954 Bug: 29759773 Change-Id: Ib8c983af4dbbfee68edb60937b268e2c1a9b5e64
2016-06-29 11:23:25 -07:00
parent 25242a7bbc
commit 9c0eb0bd46
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
@@ -39065,7 +39065,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);
@@ -39132,7 +39132,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) {