From 467acc47a31c3c299616ca5c6aef003e9a067e54 Mon Sep 17 00:00:00 2001 From: Tyler Gunn Date: Wed, 7 Oct 2020 15:42:06 -0700 Subject: [PATCH] CallScreeningService API docs cleanup. Cleanups for call screening service APIs and to provide more clarity for the lifecycle of the service. Fixes: 170286897 Test: make docs ; preview docs genreated. Change-Id: I487b438e39abb83cee1bd050889a6bce164247d7 --- .../android/telecom/CallScreeningService.java | 52 ++++++++++++++++--- 1 file changed, 45 insertions(+), 7 deletions(-) diff --git a/telecomm/java/android/telecom/CallScreeningService.java b/telecomm/java/android/telecom/CallScreeningService.java index 4d9311c282f7a..49f183151e278 100644 --- a/telecomm/java/android/telecom/CallScreeningService.java +++ b/telecomm/java/android/telecom/CallScreeningService.java @@ -64,7 +64,7 @@ import com.android.internal.telecom.ICallScreeningService; * * *

- *

Becoming the {@link CallScreeningService}

+ *

Becoming the CallScreeningService

* Telecom will bind to a single app chosen by the user which implements the * {@link CallScreeningService} API when there are new incoming and outgoing calls. *

@@ -90,7 +90,27 @@ import com.android.internal.telecom.ICallScreeningService; * } * } * } + * } * + * + *

CallScreeningService Lifecycle

+ * + * The framework binds to the {@link CallScreeningService} implemented by the user-chosen app + * filling the {@link android.app.role.RoleManager#ROLE_CALL_SCREENING} role when incoming calls are + * received (prior to ringing) and when outgoing calls are placed. The platform calls the + * {@link #onScreenCall(Call.Details)} method to provide your service with details about the call. + *

+ * For incoming calls, the {@link CallScreeningService} must call + * {@link #respondToCall(Call.Details, CallResponse)} within 5 seconds of being bound to indicate to + * the platform whether the call should be blocked or not. Your app must do this even if it is + * primarily performing caller ID operations and not screening calls. It is important to perform + * screening operations in a timely matter as the user's device will not begin ringing until the + * response is received (or the timeout is hit). A {@link CallScreeningService} may choose to + * perform local database lookups to help determine if a call should be screened or not; care should + * be taken to ensure the timeout is not repeatedly hit, causing delays in the incoming call flow. + *

+ * If your app provides a caller ID experience, it should launch an activity to show the caller ID + * information from {@link #onScreenCall(Call.Details)}. */ public abstract class CallScreeningService extends Service { /** @@ -339,7 +359,7 @@ public abstract class CallScreeningService extends Service { } /** - * Called when a new incoming or outgoing call is added which is not in the user's contact list. + * Called when a new incoming or outgoing call is added. *

* A {@link CallScreeningService} must indicate whether an incoming call is allowed or not by * calling @@ -347,21 +367,32 @@ public abstract class CallScreeningService extends Service { * Your app can tell if a call is an incoming call by checking to see if * {@link Call.Details#getCallDirection()} is {@link Call.Details#DIRECTION_INCOMING}. *

- * Note: The {@link Call.Details} instance provided to a call screening service will only have - * the following properties set. The rest of the {@link Call.Details} properties will be set to - * their default value or {@code null}. + * Note: A {@link CallScreeningService} must respond to a call within 5 seconds. After + * this time, the framework will unbind from the {@link CallScreeningService} and ignore its + * response. + *

+ * Note: The {@link Call.Details} instance provided to a call screening service will + * only have the following properties set. The rest of the {@link Call.Details} properties will + * be set to their default value or {@code null}. *

*

* Only calls where the {@link Call.Details#getHandle() handle} {@link Uri#getScheme() scheme} * is {@link PhoneAccount#SCHEME_TEL} are passed for call * screening. Further, only calls which are not in the user's contacts are passed for - * screening. For outgoing calls, no post-dial digits are passed. + * screening, unless the {@link CallScreeningService} has been granted + * {@link Manifest.permission#READ_CONTACTS} permission by the user. For outgoing calls, no + * post-dial digits are passed. + *

+ * Calls with a {@link Call.Details#getHandlePresentation()} of + * {@link TelecomManager#PRESENTATION_RESTRICTED}, {@link TelecomManager#PRESENTATION_UNKNOWN} + * or {@link TelecomManager#PRESENTATION_PAYPHONE} presentation are not provided to the + * {@link CallScreeningService}. * * @param callDetails Information about a new call, see {@link Call.Details}. */ @@ -376,6 +407,13 @@ public abstract class CallScreeningService extends Service { *

* Calls to this method are ignored unless the {@link Call.Details#getCallDirection()} is * {@link Call.Details#DIRECTION_INCOMING}. + *

+ * For incoming calls, a {@link CallScreeningService} MUST call this method within 5 seconds of + * {@link #onScreenCall(Call.Details)} being invoked by the platform. + *

+ * Calls which are blocked/rejected will be logged to the system call log with a call type of + * {@link android.provider.CallLog.Calls#BLOCKED_TYPE} and + * {@link android.provider.CallLog.Calls#BLOCK_REASON_CALL_SCREENING_SERVICE} block reason. * * @param callDetails The call to allow. *