Merge "API cleanups per API review." into nyc-mr1-dev
diff --git a/api/current.txt b/api/current.txt
index 790ade4..c860507 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -36218,7 +36218,7 @@
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 @@
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);
diff --git a/api/system-current.txt b/api/system-current.txt
index 62dbd0c..aa26649 100644
--- a/api/system-current.txt
+++ b/api/system-current.txt
@@ -39066,7 +39066,7 @@
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 @@
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);
diff --git a/api/test-current.txt b/api/test-current.txt
index 4854dae..81a824e 100644
--- a/api/test-current.txt
+++ b/api/test-current.txt
@@ -36296,7 +36296,7 @@
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 @@
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);
diff --git a/telecomm/java/android/telecom/Call.java b/telecomm/java/android/telecom/Call.java
index 3a6d1fd..62625bdf 100644
--- a/telecomm/java/android/telecom/Call.java
+++ b/telecomm/java/android/telecom/Call.java
@@ -701,6 +701,24 @@
}
}
+ /**
+ * 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 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 @@
* 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.
diff --git a/telecomm/java/android/telecom/Conference.java b/telecomm/java/android/telecom/Conference.java
index 0eabf15..a012082 100644
--- a/telecomm/java/android/telecom/Conference.java
+++ b/telecomm/java/android/telecom/Conference.java
@@ -256,60 +256,63 @@
}
/**
- * 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 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 @@
* 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
diff --git a/telecomm/java/android/telecom/Connection.java b/telecomm/java/android/telecom/Connection.java
index 1b14d65..4ce4ddd 100644
--- a/telecomm/java/android/telecom/Connection.java
+++ b/telecomm/java/android/telecom/Connection.java
@@ -53,6 +53,37 @@
* 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 @@
/**
* 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 @@
/**
* 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 @@
* {@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 @@
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 @@
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 @@
* 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 @@
* <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 @@
}
/**
- * 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) {