Merge "Telecom API doc cleanup." into qt-dev

/**

 * This service is implemented by an app that wishes to provide functionality for managing

 * phone calls.

 * <p>

 * There are three types of apps which Telecom can bind to when there exists a live (active or

 * incoming) call:

 * <ol>

 *     <li>Default Dialer/Phone app - the default dialer/phone app is one which provides the

 *     in-call user interface while the device is in a call.  A device is bundled with a system

 *     provided default dialer/phone app.  The user may choose a single app to take over this role

 *     from the system app.</li>

 *     <li>Default Car-mode Dialer/Phone app - the default car-mode dialer/phone app is one which

 *     provides the in-call user interface while the device is in a call and the device is in car

 *     mode.  The user may choose a single app to fill this role.</li>

 *     <li>Call Companion app - a call companion app is one which provides no user interface itself,

 *     but exposes call information to another display surface, such as a wearable device.  The

 *     user may choose multiple apps to fill this role.</li>

 * </ol>

 * <p>

 * Apps which wish to fulfill one of the above roles use the {@link android.app.role.RoleManager}

 * to request that they fill the desired role.

 *

 * <h2>Becoming the Default Phone App</h2>

 * The default dialer/phone app is one which provides the in-call user interface while the device is

 * in a call.  A device is bundled with a system provided default dialer/phone app.  The user may

 * choose a single app to take over this role from the system app.  An app which wishes to fulfill

 * one this role uses the {@code android.app.role.RoleManager} to request that they fill the role.

 * <p>

 * An app filling the role of the default phone app provides a user interface while the device is in

 * a call, and the device is not in car mode.

 * <p>

 * notificationManager.notify(YOUR_CHANNEL_ID, YOUR_TAG, YOUR_ID, builder.build());

 * }</pre>

 * <p>

 * <h2>Becoming the Default Car-mode Phone App</h2>

 * An app filling the role of the default car-mode dialer/phone app provides a user interface while

 * the device is in a call, and in car mode.  See

 * {@link android.app.UiModeManager#ACTION_ENTER_CAR_MODE} for more information about car mode.

 * When the device is in car mode, Telecom binds to the default car-mode dialer/phone app instead

 * of the usual dialer/phone app.

 * <p>

 * Similar to the requirements for becoming the default dialer/phone app, your app must declare a

 * manifest entry for its {@link InCallService} implementation.  Your manifest entry should ensure

 * the following conditions are met:

 * <ul>

 *     <li>Do NOT declare the {@link TelecomManager#METADATA_IN_CALL_SERVICE_UI} metadata.</li>

 *     <li>Set the {@link TelecomManager#METADATA_IN_CALL_SERVICE_CAR_MODE_UI} metadata to

 *     {@code true}<li>

 *     <li>Your app must request the permission

 *     {@link android.Manifest.permission.CALL_COMPANION_APP}.</li>

 * </ul>

 * <p>

 * Your app should request to fill the role {@code android.app.role.CAR_MODE_DIALER} in order to

 * become the default (see <a href="#requestRole">above</a> for how to request your app fills this

 * role).

 *

 * <h2>Becoming a Call Companion App</h2>

 * An app which fills the companion app role does not directly provide a user interface while the

 * device is in a call.  Instead, it is typically used to relay information about calls to another

 * display surface, such as a wearable device.

 * <p>

 * Similar to the requirements for becoming the default dialer/phone app, your app must declare a

 * manifest entry for its {@link InCallService} implementation.  Your manifest entry should

 * ensure the following conditions are met:

 * <ul>

 *     <li>Do NOT declare the {@link TelecomManager#METADATA_IN_CALL_SERVICE_UI} metadata.</li>

 *     <li>Do NOT declare the {@link TelecomManager#METADATA_IN_CALL_SERVICE_CAR_MODE_UI}

 *     metadata.</li>

 *     <li>Your app must request the permission

 *     {@link android.Manifest.permission.CALL_COMPANION_APP}.</li>

 * </ul>

 * <p>

 * Your app should request to fill the role {@code android.app.role.CALL_COMPANION} in order to

 * become a call companion app (see <a href="#requestRole">above</a> for how to request your app

 * fills this role).

 */

public abstract class InCallService extends Service {

import android.Manifest;

import android.annotation.IntDef;

import android.annotation.NonNull;

import android.annotation.Nullable;

import android.annotation.RequiresPermission;

import android.annotation.SuppressAutoDoc;

     * Dialer implementations (see {@link #getDefaultDialerPackage()}) which would also like to

     * override the system provided ringing should set this meta-data to {@code true} in the

     * manifest registration of their {@link InCallService}.

     * <p>

     * When {@code true}, it is the {@link InCallService}'s responsibility to play a ringtone for

     * all incoming calls.

     */

    public static final String METADATA_IN_CALL_SERVICE_RINGING =

            "android.telecom.IN_CALL_SERVICE_RINGING";

    /**

     * Silences the ringer if a ringing call exists.

     *

     * Requires permission: {@link android.Manifest.permission#MODIFY_PHONE_STATE}

     * <p>

     * This method can only be relied upon to stop the ringtone for a call if the ringtone has

     * already started playing.  It is intended to handle use-cases such as silencing a ringing call

     * when the user presses the volume button during ringing.

     * <p>

     * If this method is called prior to when the ringtone begins playing, the ringtone will not be

     * silenced.  As such it is not intended as a means to avoid playing of a ringtone.

     * <p>

     * A dialer app which wants to have more control over ringtone playing should declare

     * {@link TelecomManager#METADATA_IN_CALL_SERVICE_RINGING} in the manifest entry for their

     * {@link InCallService} implementation to indicate that the app wants to be responsible for

     * playing the ringtone for all incoming calls.

     * <p>

     * Requires permission: {@link android.Manifest.permission#MODIFY_PHONE_STATE} or that the

     * app fills the dialer role (see {@link #getDefaultDialerPackage()}).

     */

    @RequiresPermission(android.Manifest.permission.MODIFY_PHONE_STATE)

    public void silenceRinger() {