From 272fd21493416f5b02f92471f03c77741be89440 Mon Sep 17 00:00:00 2001
From: Tyler Gunn <tgunn@google.com>
Date: Tue, 12 Oct 2021 09:22:24 -0700
Subject: [PATCH] API docs clarification for placing calls.

Clarifying that a dialer app should use TelecomManager to place calls
instead of relying on the Intent#ACTION_CALL intent.

Test: Docs only change.
Fixes: 202033596
Change-Id: Iac9358c5cd069f120a167c96aa6b9462313b2268
---
 core/java/android/content/Intent.java            | 4 ++++
 telecomm/java/android/telecom/InCallService.java | 9 ++++++++-
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/core/java/android/content/Intent.java b/core/java/android/content/Intent.java
index 0fad63f192bba..5d0f6d5fba6d2 100644
--- a/core/java/android/content/Intent.java
+++ b/core/java/android/content/Intent.java
@@ -1127,6 +1127,10 @@ public class Intent implements Parcelable, Cloneable {
      * numbers.  Applications can <strong>dial</strong> emergency numbers using
      * {@link #ACTION_DIAL}, however.
      *
+     * <p>Note: An app filling the {@link android.app.role.RoleManager#ROLE_DIALER} role should use
+     * {@link android.telecom.TelecomManager#placeCall(Uri, Bundle)} to place calls rather than
+     * relying on this intent.
+     *
      * <p>Note: if you app targets {@link android.os.Build.VERSION_CODES#M M}
      * and above and declares as using the {@link android.Manifest.permission#CALL_PHONE}
      * permission which is not granted, then attempting to use this action will
diff --git a/telecomm/java/android/telecom/InCallService.java b/telecomm/java/android/telecom/InCallService.java
index 705b4918726ea..7caaba71222f5 100644
--- a/telecomm/java/android/telecom/InCallService.java
+++ b/telecomm/java/android/telecom/InCallService.java
@@ -69,7 +69,14 @@ import java.util.List;
  * them know that the app has crashed and that their call was continued using the pre-loaded dialer
  * app.
  * <p>
- * Further, the pre-loaded dialer will ALWAYS be used when the user places an emergency call.
+ * The pre-loaded dialer will ALWAYS be used when the user places an emergency call, even if your
+ * app fills the {@link android.app.role.RoleManager#ROLE_DIALER} role.  To ensure an optimal
+ * experience when placing an emergency call, the default dialer should ALWAYS use
+ * {@link android.telecom.TelecomManager#placeCall(Uri, Bundle)} to place calls (including
+ * emergency calls).  This ensures that the platform is able to verify that the request came from
+ * the default dialer.  If a non-preloaded dialer app uses {@link Intent#ACTION_CALL} to place an
+ * emergency call, it will be raised to the preloaded dialer app using {@link Intent#ACTION_DIAL}
+ * for confirmation; this is a suboptimal user experience.
  * <p>
  * Below is an example manifest registration for an {@code InCallService}. The meta-data
  * {@link TelecomManager#METADATA_IN_CALL_SERVICE_UI} indicates that this particular