API Review cleanups.
- New @SystemApis on Conference and PhoneAccount were missing the required permissions annotations. - Rename PROPERTY_ASSISTED_DIALING_USED to PROPERTY_ASSISTED_DIALING - Standardize get/setConnectionStartElapsedRealtimeMillis method naming across Connection and Conference classes. - Clarify Conference#sendConferenceEvent API documentation to match the docs present for similar method in Connection; include some examples of valid event/extras combinations. - Update TelecomManager#getDefaultdialerPackage to use UserHandle instead of userId. - Move Conference#getConnectionStartElapsedRealtimeMillis to public API since the setter is already part of the public API. Test: Run Telecom and Telephony CTS tests. Test: Run Telephony unit tests. Test: Perform manual single-party-conference regression test to confirm that conference behavior does not regress. Bug: 147301297 Bug: 148286830 Bug: 148284863 Bug: 148284843 Bug: 148287068 Bug: 148285484 Bug: 148285560 Change-Id: I1f446d81859fa109d74af3661a42a0bd224de5aa Merged-In: I1f446d81859fa109d74af3661a42a0bd224de5aa
This commit is contained in:
Tyler Gunn
@@ -16,8 +16,13 @@
|
||||
|
||||
package android.telecom;
|
||||
|
||||
import static android.Manifest.permission.MODIFY_PHONE_STATE;
|
||||
|
||||
import android.annotation.ElapsedRealtimeLong;
|
||||
import android.annotation.IntRange;
|
||||
import android.annotation.NonNull;
|
||||
import android.annotation.Nullable;
|
||||
import android.annotation.RequiresPermission;
|
||||
import android.annotation.SystemApi;
|
||||
import android.annotation.TestApi;
|
||||
import android.net.Uri;
|
||||
@@ -620,12 +625,12 @@ public abstract class Conference extends Conferenceable {
|
||||
* Should be specified in wall-clock time returned by {@link System#currentTimeMillis()}.
|
||||
* <p>
|
||||
* When setting the connection time, you should always set the connection elapsed time via
|
||||
* {@link #setConnectionStartElapsedRealTime(long)} to ensure the duration is reflected.
|
||||
* {@link #setConnectionStartElapsedRealtimeMillis(long)} to ensure the duration is reflected.
|
||||
*
|
||||
* @param connectionTimeMillis The connection time, in milliseconds, as returned by
|
||||
* {@link System#currentTimeMillis()}.
|
||||
*/
|
||||
public final void setConnectionTime(long connectionTimeMillis) {
|
||||
public final void setConnectionTime(@IntRange(from = 0) long connectionTimeMillis) {
|
||||
mConnectTimeMillis = connectionTimeMillis;
|
||||
}
|
||||
|
||||
@@ -641,8 +646,28 @@ public abstract class Conference extends Conferenceable {
|
||||
*
|
||||
* @param connectionStartElapsedRealTime The connection time, as measured by
|
||||
* {@link SystemClock#elapsedRealtime()}.
|
||||
* @deprecated use {@link #setConnectionStartElapsedRealtimeMillis(long)} instead.
|
||||
*/
|
||||
@Deprecated
|
||||
public final void setConnectionStartElapsedRealTime(long connectionStartElapsedRealTime) {
|
||||
setConnectionStartElapsedRealtimeMillis(connectionStartElapsedRealTime);
|
||||
}
|
||||
|
||||
/**
|
||||
* Sets the start time of the {@link Conference} which is the basis for the determining the
|
||||
* duration of the {@link Conference}.
|
||||
* <p>
|
||||
* You should use a value returned by {@link SystemClock#elapsedRealtime()} to ensure that time
|
||||
* zone changes do not impact the conference duration.
|
||||
* <p>
|
||||
* When setting this, you should also set the connection time via
|
||||
* {@link #setConnectionTime(long)}.
|
||||
*
|
||||
* @param connectionStartElapsedRealTime The connection time, as measured by
|
||||
* {@link SystemClock#elapsedRealtime()}.
|
||||
*/
|
||||
public final void setConnectionStartElapsedRealtimeMillis(
|
||||
@ElapsedRealtimeLong long connectionStartElapsedRealTime) {
|
||||
mConnectionStartElapsedRealTime = connectionStartElapsedRealTime;
|
||||
}
|
||||
|
||||
@@ -663,7 +688,7 @@ public abstract class Conference extends Conferenceable {
|
||||
*
|
||||
* @return The time at which the {@code Conference} was connected.
|
||||
*/
|
||||
public final long getConnectionTime() {
|
||||
public final @IntRange(from = 0) long getConnectionTime() {
|
||||
return mConnectTimeMillis;
|
||||
}
|
||||
|
||||
@@ -680,11 +705,8 @@ public abstract class Conference extends Conferenceable {
|
||||
* has no general use other than to the Telephony framework.
|
||||
*
|
||||
* @return The elapsed time at which the {@link Conference} was connected.
|
||||
* @hide
|
||||
*/
|
||||
@SystemApi
|
||||
@TestApi
|
||||
public final long getConnectionStartElapsedRealTime() {
|
||||
public final @ElapsedRealtimeLong long getConnectionStartElapsedRealtimeMillis() {
|
||||
return mConnectionStartElapsedRealTime;
|
||||
}
|
||||
|
||||
@@ -981,6 +1003,7 @@ public abstract class Conference extends Conferenceable {
|
||||
*/
|
||||
@SystemApi
|
||||
@TestApi
|
||||
@RequiresPermission(MODIFY_PHONE_STATE)
|
||||
public void setConferenceState(boolean isConference) {
|
||||
for (Listener l : mListeners) {
|
||||
l.onConferenceStateChanged(this, isConference);
|
||||
@@ -1001,6 +1024,7 @@ public abstract class Conference extends Conferenceable {
|
||||
*/
|
||||
@SystemApi
|
||||
@TestApi
|
||||
@RequiresPermission(MODIFY_PHONE_STATE)
|
||||
public final void setAddress(@NonNull Uri address,
|
||||
@TelecomManager.Presentation int presentation) {
|
||||
Log.d(this, "setAddress %s", address);
|
||||
@@ -1107,12 +1131,52 @@ public abstract class Conference extends Conferenceable {
|
||||
}
|
||||
|
||||
/**
|
||||
* Sends an event associated with this {@code Conference} with associated event extras to the
|
||||
* {@link InCallService} (note: this is identical in concept to
|
||||
* {@link Connection#sendConnectionEvent(String, Bundle)}).
|
||||
* @see Connection#sendConnectionEvent(String, Bundle)
|
||||
* Sends an event associated with this {@link Conference} with associated event extras to the
|
||||
* {@link InCallService}.
|
||||
* <p>
|
||||
* Connection events are used to communicate point in time information from a
|
||||
* {@link ConnectionService} to an {@link InCallService} implementation. 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 Connection#EVENT_MERGE_COMPLETE}
|
||||
* connection event when a call to {@link Call#mergeConference()} has completed successfully.
|
||||
* <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.
|
||||
* 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.
|
||||
* <p>
|
||||
* Expected connection events from the Telephony stack are:
|
||||
* <p>
|
||||
* <ul>
|
||||
* <li>{@link Connection#EVENT_CALL_HOLD_FAILED} with {@code null} {@code extras} when the
|
||||
* {@link Conference} could not be held.</li>
|
||||
* <li>{@link Connection#EVENT_MERGE_START} with {@code null} {@code extras} when a new
|
||||
* call is being merged into the conference.</li>
|
||||
* <li>{@link Connection#EVENT_MERGE_COMPLETE} with {@code null} {@code extras} a new call
|
||||
* has completed being merged into the conference.</li>
|
||||
* <li>{@link Connection#EVENT_CALL_MERGE_FAILED} with {@code null} {@code extras} a new
|
||||
* call has failed to merge into the conference (the dialer app can determine which call
|
||||
* failed to merge based on the fact that the call still exists outside of the conference
|
||||
* at the end of the merge process).</li>
|
||||
* </ul>
|
||||
*
|
||||
* @param event The connection event.
|
||||
* @param event The conference event.
|
||||
* @param extras Optional bundle containing extra information associated with the event.
|
||||
*/
|
||||
public void sendConferenceEvent(@NonNull String event, @Nullable Bundle extras) {
|
||||
|
||||
Reference in New Issue
Block a user