* Below is an example manifest registration for a {@code CallScreeningService}. *
* {@code
*
*
*
*
* }
*
* * A CallScreeningService performs two functions: *
*
* The code snippet below illustrates how your app can request that it fills the call screening * role. *
* {@code
* private static final int REQUEST_ID = 1;
*
* public void requestRole() {
* RoleManager roleManager = (RoleManager) getSystemService(ROLE_SERVICE);
* Intent intent = roleManager.createRequestRoleIntent("android.app.role.CALL_SCREENING");
* startActivityForResult(intent, REQUEST_ID);
* }
*
* @Override
* public void onActivityResult(int requestCode, int resultCode, Intent data) {
* if (requestCode == REQUEST_ID) {
* if (resultCode == android.app.Activity.RESULT_OK) {
* // Your app is now the call screening app
* } else {
* // Your app is not the call screening app
* }
* }
* }
*
*/
public abstract class CallScreeningService extends Service {
/** @hide */
@Retention(RetentionPolicy.SOURCE)
@IntDef(
prefix = { "CALL_DURATION_" },
value = {CALL_DURATION_VERY_SHORT, CALL_DURATION_SHORT, CALL_DURATION_MEDIUM,
CALL_DURATION_LONG})
public @interface CallDuration {}
/**
* Call duration reported with {@link #EXTRA_CALL_DURATION} to indicate to the
* {@link CallScreeningService} the duration of a call for which the user reported the nuisance
* status (see {@link TelecomManager#reportNuisanceCallStatus(Uri, boolean)}). The
* {@link CallScreeningService} can use this as a signal for training nuisance detection
* algorithms. The call duration is reported in coarse grained buckets to minimize exposure of
* identifying call log information to the {@link CallScreeningService}.
* * Indicates the call was < 3 seconds in duration. */ public static final int CALL_DURATION_VERY_SHORT = 1; /** * Call duration reported with {@link #EXTRA_CALL_DURATION} to indicate to the * {@link CallScreeningService} the duration of a call for which the user reported the nuisance * status (see {@link TelecomManager#reportNuisanceCallStatus(Uri, boolean)}). The * {@link CallScreeningService} can use this as a signal for training nuisance detection * algorithms. The call duration is reported in coarse grained buckets to minimize exposure of * identifying call log information to the {@link CallScreeningService}. *
* Indicates the call was greater than 3 seconds, but less than 60 seconds in duration. */ public static final int CALL_DURATION_SHORT = 2; /** * Call duration reported with {@link #EXTRA_CALL_DURATION} to indicate to the * {@link CallScreeningService} the duration of a call for which the user reported the nuisance * status (see {@link TelecomManager#reportNuisanceCallStatus(Uri, boolean)}). The * {@link CallScreeningService} can use this as a signal for training nuisance detection * algorithms. The call duration is reported in coarse grained buckets to minimize exposure of * identifying call log information to the {@link CallScreeningService}. *
* Indicates the call was greater than 60 seconds, but less than 120 seconds in duration. */ public static final int CALL_DURATION_MEDIUM = 3; /** * Call duration reported with {@link #EXTRA_CALL_DURATION} to indicate to the * {@link CallScreeningService} the duration of a call for which the user reported the nuisance * status (see {@link TelecomManager#reportNuisanceCallStatus(Uri, boolean)}). The * {@link CallScreeningService} can use this as a signal for training nuisance detection * algorithms. The call duration is reported in coarse grained buckets to minimize exposure of * identifying call log information to the {@link CallScreeningService}. *
* Indicates the call was greater than 120 seconds. */ public static final int CALL_DURATION_LONG = 4; /** * Telecom sends this intent to the {@link CallScreeningService} which the user has chosen to * fill the call screening role when the user indicates through the default dialer whether a * call is a nuisance call or not (see * {@link TelecomManager#reportNuisanceCallStatus(Uri, boolean)}). *
* The following extra values are provided for the call: *
* {@link CallScreeningService} implementations which want to track whether the user reports * calls are nuisance calls should use declare a broadcast receiver in their manifest for this * intent. *
* Note: Only {@link CallScreeningService} implementations which have provided * {@link CallIdentification} information for calls at some point will receive this intent. */ public static final String ACTION_NUISANCE_CALL_STATUS_CHANGED = "android.telecom.action.NUISANCE_CALL_STATUS_CHANGED"; /** * Extra used to provide the handle of the call for * {@link #ACTION_NUISANCE_CALL_STATUS_CHANGED}. The call handle is reported as a * {@link Uri}. */ public static final String EXTRA_CALL_HANDLE = "android.telecom.extra.CALL_HANDLE"; /** * Boolean extra used to indicate whether the user reported a call as a nuisance call. * When {@code true}, the user reported that a call was a nuisance call, {@code false} * otherwise. Sent with {@link #ACTION_NUISANCE_CALL_STATUS_CHANGED}. */ public static final String EXTRA_IS_NUISANCE = "android.telecom.extra.IS_NUISANCE"; /** * Integer extra used with {@link #ACTION_NUISANCE_CALL_STATUS_CHANGED} to report the type of * call. Valid values are: *
* Note: Calls will still be logged with type * {@link android.provider.CallLog.Calls#BLOCKED_TYPE}, regardless of how this property * is set. */ public Builder setSkipCallLog(boolean shouldSkipCallLog) { mShouldSkipCallLog = shouldSkipCallLog; return this; } /** * Sets whether a missed call notification should not be shown for the incoming call. * This property should only be set to true if the call is disallowed. */ public Builder setSkipNotification(boolean shouldSkipNotification) { mShouldSkipNotification = shouldSkipNotification; return this; } public CallResponse build() { return new CallResponse( mShouldDisallowCall, mShouldRejectCall, mShouldSkipCallLog, mShouldSkipNotification); } } } public CallScreeningService() { } @Override public IBinder onBind(Intent intent) { Log.v(this, "onBind"); return new CallScreeningBinder(); } @Override public boolean onUnbind(Intent intent) { Log.v(this, "onUnbind"); return false; } /** * Called when a new incoming or outgoing call is added which is not in the user's contact list. *
* A {@link CallScreeningService} must indicate whether an incoming call is allowed or not by * calling * {@link CallScreeningService#respondToCall(Call.Details, CallScreeningService.CallResponse)}. * 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}. *
* For incoming or outgoing calls, the {@link CallScreeningService} can call * {@link #provideCallIdentification(Call.Details, CallIdentification)} in order to provide * {@link CallIdentification} for the call. *
* 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. * * @param callDetails Information about a new call, see {@link Call.Details}. */ public abstract void onScreenCall(@NonNull Call.Details callDetails); /** * Responds to the given incoming call, either allowing it or disallowing it. *
* The {@link CallScreeningService} calls this method to inform the system whether the call * should be silently blocked or not. *
* Calls to this method are ignored unless the {@link Call.Details#getCallDirection()} is * {@link Call.Details#DIRECTION_INCOMING}. * * @param callDetails The call to allow. *
* Must be the same {@link Call.Details call} which was provided to the * {@link CallScreeningService} via {@link #onScreenCall(Call.Details)}. * @param response The {@link CallScreeningService.CallResponse} which contains information * about how to respond to a call. */ public final void respondToCall(@NonNull Call.Details callDetails, @NonNull CallResponse response) { try { if (response.getDisallowCall()) { mCallScreeningAdapter.disallowCall( callDetails.getTelecomCallId(), response.getRejectCall(), !response.getSkipCallLog(), !response.getSkipNotification(), new ComponentName(getPackageName(), getClass().getName())); } else { mCallScreeningAdapter.allowCall(callDetails.getTelecomCallId()); } } catch (RemoteException e) { } } /** * Provide {@link CallIdentification} information about a {@link Call.Details call}. *
* The {@link CallScreeningService} calls this method to provide information it has identified * about a {@link Call.Details call}. This information will potentially be shown to the user * in the {@link InCallService dialer} app. It will be logged to the * {@link android.provider.CallLog}. *
* A {@link CallScreeningService} should only call this method for calls for which it is able to * provide some {@link CallIdentification} for. {@link CallIdentification} instances with no * fields set will be ignored by the system. * * @param callDetails The call to provide information for. *
* Must be the same {@link Call.Details call} which was provided to the * {@link CallScreeningService} via {@link #onScreenCall(Call.Details)}. * @param identification An instance of {@link CallIdentification} with information about the * {@link Call.Details call}. */ public final void provideCallIdentification(@NonNull Call.Details callDetails, @NonNull CallIdentification identification) { try { mCallScreeningAdapter.provideCallIdentification(callDetails.getTelecomCallId(), identification); } catch (RemoteException e) { } } }