CallScreeningService


public abstract class CallScreeningService
extends Service

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.telecom.CallScreeningService


This service can be implemented by the default dialer (see TelecomManager.getDefaultDialerPackage()) or a third party app to allow or disallow incoming calls before they are shown to a user. A CallScreeningService can also see outgoing calls for the purpose of providing caller ID services for those calls.

Below is an example manifest registration for a CallScreeningService.

<service android:name="your.package.YourCallScreeningServiceImplementation"
         android:permission="android.permission.BIND_SCREENING_SERVICE">
     <intent-filter>
         <action android:name="android.telecom.CallScreeningService"/>
     </intent-filter>
</service>

A CallScreeningService performs two functions:

  1. Call blocking/screening - the service can choose which calls will ring on the user's device, and which will be silently sent to voicemail.
  2. Call identification - services which provide call identification functionality can display a user-interface of their choosing which contains identifying information for a call.

Becoming the CallScreeningService

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

The code snippet below illustrates how your app can request that it fills the call screening role.

private static final int REQUEST_ID = 1;

public void requestRole() {
    RoleManager roleManager = (RoleManager) getSystemService(ROLE_SERVICE);
    Intent intent = roleManager.createRequestRoleIntent(RoleManager.ROLE_CALL_SCREENING);
    startActivityForResult(intent, REQUEST_ID);
}

&#64;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
        }
    }
}

CallScreeningService Lifecycle

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

For incoming calls, the CallScreeningService must call 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 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 onScreenCall(Call.Details).

Summary

Nested classes

class CallScreeningService.CallResponse

Information about how to respond to an incoming call. 

Constants

String SERVICE_INTERFACE

The Intent that must be declared as handled by the service.

Inherited constants

Public constructors

CallScreeningService()

Public methods

IBinder onBind(Intent intent)

Return the communication channel to the service.

abstract void onScreenCall(Call.Details callDetails)

Called when a new incoming or outgoing call is added.

boolean onUnbind(Intent intent)

Called when all clients have disconnected from a particular interface published by the service.

final void respondToCall(Call.Details callDetails, CallScreeningService.CallResponse response)

Responds to the given incoming call, either allowing it, silencing it or disallowing it.

Inherited methods