Merge "API cleanups per API review." into nyc-mr1-dev (138a3f3a) · Commits · e / os / android_frameworks_base

api/current.txt

+2 −2

Original line number	Diff line number	Diff line
		@@ -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);

api/system-current.txt

+2 −2

Original line number	Diff line number	Diff line
		@@ -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);

api/test-current.txt

+2 −2

Original line number	Diff line number	Diff line
		@@ -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);

telecomm/java/android/telecom/Call.java

+47 −2

Original line number	Diff line number	Diff line
		@@ -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.

telecomm/java/android/telecom/Conference.java

+22 −17

Original line number	Diff line number	Diff line
		@@ -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