Merge "CallScreeningService API docs cleanup." am: 834c527a

 *     </li>

 * </ol>

 * <p>

 * <h2>Becoming the {@link CallScreeningService}</h2>

 * <h2>Becoming the CallScreeningService</h2>

 * 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.

 * <p>

 *         }

 *     }

 * }

 * }

 * </pre>

 *

 * <h2>CallScreeningService Lifecycle</h2>

 *

 * 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.

 * <p>

 * 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.

 * <p>

 * 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 {

    /**

    }

    /**

     * 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.

     * <p>

     * A {@link CallScreeningService} must indicate whether an incoming call is allowed or not by

     * calling

     * 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}.

     * <p>

     * 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}.

     * <em>Note:</em> 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.

     * <p>

     * <em>Note:</em> 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}.

     * <ul>

     *     <li>{@link Call.Details#getCallDirection()}</li>

     *     <li>{@link Call.Details#getCallerNumberVerificationStatus()}</li>

     *     <li>{@link Call.Details#getConnectTimeMillis()}</li>

     *     <li>{@link Call.Details#getCreationTimeMillis()}</li>

     *     <li>{@link Call.Details#getHandle()}</li>

     *     <li>{@link Call.Details#getHandlePresentation()}</li>

     * </ul>

     * <p>

     * 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.

     * <p>

     * 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}.

     */

     * <p>

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

     * {@link Call.Details#DIRECTION_INCOMING}.

     * <p>

     * For incoming calls, a {@link CallScreeningService} MUST call this method within 5 seconds of

     * {@link #onScreenCall(Call.Details)} being invoked by the platform.

     * <p>

     * 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.

     *                    <p>