Telecom API doc cleanup.
InCallService - remove references to roles cut in Q release.
TelecomManager - make it more clear how to use the silenceRinger method
and under which conditions it should be used.
Test: Compile; docs only.
Fixes: 130285730
Change-Id: I55f9c2df119140666f8167e8521a4372d1108e7a
diff --git a/telecomm/java/android/telecom/InCallService.java b/telecomm/java/android/telecom/InCallService.java
index cbcd40f..ebfa3a1 100644
--- a/telecomm/java/android/telecom/InCallService.java
+++ b/telecomm/java/android/telecom/InCallService.java
@@ -41,26 +41,12 @@
/**
* This service is implemented by an app that wishes to provide functionality for managing
* phone calls.
- * <p>
- * There are three types of apps which Telecom can bind to when there exists a live (active or
- * incoming) call:
- * <ol>
- * <li>Default Dialer/Phone app - the default dialer/phone app is one which provides the
- * in-call user interface while the device is in a call. A device is bundled with a system
- * provided default dialer/phone app. The user may choose a single app to take over this role
- * from the system app.</li>
- * <li>Default Car-mode Dialer/Phone app - the default car-mode dialer/phone app is one which
- * provides the in-call user interface while the device is in a call and the device is in car
- * mode. The user may choose a single app to fill this role.</li>
- * <li>Call Companion app - a call companion app is one which provides no user interface itself,
- * but exposes call information to another display surface, such as a wearable device. The
- * user may choose multiple apps to fill this role.</li>
- * </ol>
- * <p>
- * Apps which wish to fulfill one of the above roles use the {@link android.app.role.RoleManager}
- * to request that they fill the desired role.
- *
* <h2>Becoming the Default Phone App</h2>
+ * The default dialer/phone app is one which provides the in-call user interface while the device is
+ * in a call. A device is bundled with a system provided default dialer/phone app. The user may
+ * choose a single app to take over this role from the system app. An app which wishes to fulfill
+ * one this role uses the {@code android.app.role.RoleManager} to request that they fill the role.
+ * <p>
* An app filling the role of the default phone app provides a user interface while the device is in
* a call, and the device is not in car mode.
* <p>
@@ -193,47 +179,6 @@
* notificationManager.notify(YOUR_CHANNEL_ID, YOUR_TAG, YOUR_ID, builder.build());
* }</pre>
* <p>
- * <h2>Becoming the Default Car-mode Phone App</h2>
- * An app filling the role of the default car-mode dialer/phone app provides a user interface while
- * the device is in a call, and in car mode. See
- * {@link android.app.UiModeManager#ACTION_ENTER_CAR_MODE} for more information about car mode.
- * When the device is in car mode, Telecom binds to the default car-mode dialer/phone app instead
- * of the usual dialer/phone app.
- * <p>
- * Similar to the requirements for becoming the default dialer/phone app, your app must declare a
- * manifest entry for its {@link InCallService} implementation. Your manifest entry should ensure
- * the following conditions are met:
- * <ul>
- * <li>Do NOT declare the {@link TelecomManager#METADATA_IN_CALL_SERVICE_UI} metadata.</li>
- * <li>Set the {@link TelecomManager#METADATA_IN_CALL_SERVICE_CAR_MODE_UI} metadata to
- * {@code true}<li>
- * <li>Your app must request the permission
- * {@link android.Manifest.permission.CALL_COMPANION_APP}.</li>
- * </ul>
- * <p>
- * Your app should request to fill the role {@code android.app.role.CAR_MODE_DIALER} in order to
- * become the default (see <a href="#requestRole">above</a> for how to request your app fills this
- * role).
- *
- * <h2>Becoming a Call Companion App</h2>
- * An app which fills the companion app role does not directly provide a user interface while the
- * device is in a call. Instead, it is typically used to relay information about calls to another
- * display surface, such as a wearable device.
- * <p>
- * Similar to the requirements for becoming the default dialer/phone app, your app must declare a
- * manifest entry for its {@link InCallService} implementation. Your manifest entry should
- * ensure the following conditions are met:
- * <ul>
- * <li>Do NOT declare the {@link TelecomManager#METADATA_IN_CALL_SERVICE_UI} metadata.</li>
- * <li>Do NOT declare the {@link TelecomManager#METADATA_IN_CALL_SERVICE_CAR_MODE_UI}
- * metadata.</li>
- * <li>Your app must request the permission
- * {@link android.Manifest.permission.CALL_COMPANION_APP}.</li>
- * </ul>
- * <p>
- * Your app should request to fill the role {@code android.app.role.CALL_COMPANION} in order to
- * become a call companion app (see <a href="#requestRole">above</a> for how to request your app
- * fills this role).
*/
public abstract class InCallService extends Service {
diff --git a/telecomm/java/android/telecom/TelecomManager.java b/telecomm/java/android/telecom/TelecomManager.java
index 391d788..db63198 100644
--- a/telecomm/java/android/telecom/TelecomManager.java
+++ b/telecomm/java/android/telecom/TelecomManager.java
@@ -16,7 +16,6 @@
import android.Manifest;
import android.annotation.IntDef;
-import android.annotation.NonNull;
import android.annotation.Nullable;
import android.annotation.RequiresPermission;
import android.annotation.SuppressAutoDoc;
@@ -497,6 +496,9 @@
* Dialer implementations (see {@link #getDefaultDialerPackage()}) which would also like to
* override the system provided ringing should set this meta-data to {@code true} in the
* manifest registration of their {@link InCallService}.
+ * <p>
+ * When {@code true}, it is the {@link InCallService}'s responsibility to play a ringtone for
+ * all incoming calls.
*/
public static final String METADATA_IN_CALL_SERVICE_RINGING =
"android.telecom.IN_CALL_SERVICE_RINGING";
@@ -1495,8 +1497,21 @@
/**
* Silences the ringer if a ringing call exists.
- *
- * Requires permission: {@link android.Manifest.permission#MODIFY_PHONE_STATE}
+ * <p>
+ * This method can only be relied upon to stop the ringtone for a call if the ringtone has
+ * already started playing. It is intended to handle use-cases such as silencing a ringing call
+ * when the user presses the volume button during ringing.
+ * <p>
+ * If this method is called prior to when the ringtone begins playing, the ringtone will not be
+ * silenced. As such it is not intended as a means to avoid playing of a ringtone.
+ * <p>
+ * A dialer app which wants to have more control over ringtone playing should declare
+ * {@link TelecomManager#METADATA_IN_CALL_SERVICE_RINGING} in the manifest entry for their
+ * {@link InCallService} implementation to indicate that the app wants to be responsible for
+ * playing the ringtone for all incoming calls.
+ * <p>
+ * Requires permission: {@link android.Manifest.permission#MODIFY_PHONE_STATE} or that the
+ * app fills the dialer role (see {@link #getDefaultDialerPackage()}).
*/
@RequiresPermission(android.Manifest.permission.MODIFY_PHONE_STATE)
public void silenceRinger() {