API cleanups per API review. (9a5247a0) · Commits · e / os / android_frameworks_base

api/current.txt

+2 −2

api/system-current.txt

+2 −2

api/test-current.txt

+2 −2

telecomm/java/android/telecom/Call.java

+47 −2

Original line number	Original line	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 {		public static abstract class Callback {
	/**		/**
	* Invoked when the state of this {@code Call} has changed. See {@link #getState()}.		* 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) {}		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>		* <p>
	* See {@link Connection#sendConnectionEvent(String, Bundle)}.		* 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		* Sends a {@code Call} event from this {@code Call} to the associated {@link Connection} in
	* the {@link ConnectionService}.		* the {@link ConnectionService}.
	* <p>		* <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		* Events are exposed to {@link ConnectionService} implementations via
	* {@link android.telecom.Connection#onCallEvent(String, Bundle)}.		* {@link android.telecom.Connection#onCallEvent(String, Bundle)}.
	* <p>		* <p>
	* No assumptions should be made as to how a {@link ConnectionService} will handle these events.		* 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 event The connection event.
	* @param extras Bundle containing extra information associated with the event.		* @param extras Bundle containing extra information associated with the event.

telecomm/java/android/telecom/Conference.java

+22 −17

Original line number	Original line	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() {}		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.		* @param connection The connection to separate.
	*/		*/
	public void onSeparate(Connection connection) {}		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.		* @param connection The {@code Connection} to merge.
	*/		*/
	public void onMerge(Connection connection) {}		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() {}		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() {}		public void onUnhold() {}

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

	/**		/**
	* Invoked when the child calls should be swapped. Only invoked if the conference contains the		* Notifies the {@link Conference} when the child calls should be swapped. Only invoked if the
	* capability {@link Connection#CAPABILITY_SWAP_CONFERENCE}.		* conference contains the capability {@link Connection#CAPABILITY_SWAP_CONFERENCE}.
	*/		*/
	public void onSwap() {}		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.		* @param c A DTMF character.
	*/		*/
	public void onPlayDtmfTone(char c) {}		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() {}		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.		* @param state The new call audio state.
	* @deprecated Use {@link #onCallAudioStateChanged(CallAudioState)} instead.		* @deprecated Use {@link #onCallAudioStateChanged(CallAudioState)} instead.
	@@ -320,14 +323,15 @@ public abstract class Conference extends Conferenceable {
	public void onAudioStateChanged(AudioState state) {}		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.		* @param state The new call audio state.
	*/		*/
	public void onCallAudioStateChanged(CallAudioState 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.		* @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		* 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.		* in the new extras, but were present the last time {@code setExtras} was called are removed.
	* <p>		* <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.		* 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}.		* @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) {		public final void setExtras(@Nullable Bundle extras) {
	// Keeping putExtras and removeExtras in the same lock so that this operation happens as a		// Keeping putExtras and removeExtras in the same lock so that this operation happens as a