From 460b7d49a1504a65204a68f5084fe82be26aca43 Mon Sep 17 00:00:00 2001
From: Tyler Gunn <tgunn@google.com>
Date: Fri, 15 May 2020 10:19:32 -0700
Subject: [PATCH] Update audio processing API docs.

Updating the audio processing API docs to mention the fact that the app
must indicate in their InCallService and CallScreeningService service
entries that the service type is for "microphone" access, otherwise
background audio access will not be permitted.

Test: Docs only change.
Bug: 156042528
Change-Id: I3576dba445497791e6fa4e0a2fa42cf10eb1df5b
---
 telecomm/java/android/telecom/Call.java            | 13 +++++++++++--
 .../java/android/telecom/CallScreeningService.java | 14 +++++++++++++-
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/telecomm/java/android/telecom/Call.java b/telecomm/java/android/telecom/Call.java
index ead90bb4561f0..3365ab740cdea 100755
--- a/telecomm/java/android/telecom/Call.java
+++ b/telecomm/java/android/telecom/Call.java
@@ -22,6 +22,7 @@ import android.annotation.Nullable;
 import android.annotation.SystemApi;
 import android.annotation.TestApi;
 import android.compat.annotation.UnsupportedAppUsage;
+import android.content.pm.ServiceInfo;
 import android.net.Uri;
 import android.os.Build;
 import android.os.Bundle;
@@ -1635,13 +1636,21 @@ public final class Call {
 
     /**
      * Instructs Telecom to put the call into the background audio processing state.
-     *
+     * <p>
      * This method can be called either when the call is in {@link #STATE_RINGING} or
      * {@link #STATE_ACTIVE}. After Telecom acknowledges the request by setting the call's state to
      * {@link #STATE_AUDIO_PROCESSING}, your app may setup the audio paths with the audio stack in
      * order to capture and play audio on the call stream.
-     *
+     * <p>
      * This method can only be called by the default dialer app.
+     * <p>
+     * Apps built with SDK version {@link android.os.Build.VERSION_CODES#R} or later which are using
+     * the microphone as part of audio processing should specify the foreground service type using
+     * the attribute {@link android.R.attr#foregroundServiceType} in the {@link InCallService}
+     * service element of the app's manifest file.
+     * The {@link ServiceInfo#FOREGROUND_SERVICE_TYPE_MICROPHONE} attribute should be specified.
+     * @see <a href="https://developer.android.com/preview/privacy/foreground-service-types">
+     * the Android Developer Site</a> for more information.
      * @hide
      */
     @SystemApi
diff --git a/telecomm/java/android/telecom/CallScreeningService.java b/telecomm/java/android/telecom/CallScreeningService.java
index f8722f4ea653d..8abab90f775f2 100644
--- a/telecomm/java/android/telecom/CallScreeningService.java
+++ b/telecomm/java/android/telecom/CallScreeningService.java
@@ -23,6 +23,7 @@ import android.annotation.TestApi;
 import android.app.Service;
 import android.content.ComponentName;
 import android.content.Intent;
+import android.content.pm.ServiceInfo;
 import android.net.Uri;
 import android.os.Handler;
 import android.os.IBinder;
@@ -281,9 +282,20 @@ public abstract class CallScreeningService extends Service {
              * Sets whether to request background audio processing so that the in-call service can
              * screen the call further. If set to {@code true}, {@link #setDisallowCall} should be
              * called with {@code false}, and all other parameters in this builder will be ignored.
-             *
+             * <p>
              * This request will only be honored if the {@link CallScreeningService} shares the same
              * uid as the default dialer app. Otherwise, the call will go through as usual.
+             * <p>
+             * Apps built with SDK version {@link android.os.Build.VERSION_CODES#R} or later which
+             * are using the microphone as part of audio processing should specify the
+             * foreground service type using the attribute
+             * {@link android.R.attr#foregroundServiceType} in the {@link CallScreeningService}
+             * service element of the app's manifest file.
+             * The {@link ServiceInfo#FOREGROUND_SERVICE_TYPE_MICROPHONE} attribute should be
+             * specified.
+             * @see
+             * <a href="https://developer.android.com/preview/privacy/foreground-service-types">
+             *     the Android Developer Site</a> for more information.
              *
              * @param shouldScreenCallViaAudioProcessing Whether to request further call screening.
              * @hide