Merge "Prepare comments and annotations for OverlayManager public API"

import android.annotation.NonUiContext;

import android.annotation.Nullable;

import android.annotation.RequiresPermission;

import android.annotation.SuppressLint;

import android.annotation.SystemApi;

import android.annotation.SystemService;

import android.compat.Compatibility;

import android.content.Context;

import android.content.pm.PackageManager;

import android.os.Build;

import android.os.Process;

import android.os.RemoteException;

import android.os.ServiceManager;

import android.os.UserHandle;

import java.util.List;

/**

 * Updates OverlayManager state; gets information about installed overlay packages.

 *

 * <p>Users of this API must be actors of any overlays they desire to change the state of.</p>

 *

 * <p>An actor is a package responsible for managing the state of overlays targeting overlayables

 * that specify the actor. For example, an actor may enable or disable an overlay or otherwise

 * change its state.</p>

 *

 * <p>Actors are specified as part of the overlayable definition.

 *

 * <pre>{@code

 * <overlayable name="OverlayableResourcesName" actor="overlay://namespace/actorName">

 * }</pre></p>

 * OverlayManager gives apps the ability to create an {@link OverlayManagerTransaction} to

 * maintain the overlays and list the registered fabricated runtime resources overlays(FRROs).

 *

 * <p>Actors are defined through SystemConfig. Only system packages can be used.

 * The namespace "android" is reserved for use by AOSP and any "android" definitions must

 * have an implementation on device that fulfill their intended functionality.</p>

 * <p>OverlayManager returns the list of overlays to the app calling {@link

 * #getOverlayInfosForTarget(String)}. The app starts an {@link OverlayManagerTransaction} to manage

 * the overlays. The app can achieve the following by using {@link OverlayManagerTransaction}.

 *

 * <pre>{@code

 * <named-actor

 *     namespace="namespace"

 *     name="actorName"

 *     package="com.example.pkg"

 *     />

 * }</pre></p>

 *

 * <p>An actor can manipulate a particular overlay if any of the following is true:

 * <ul>

 * <li>its UID is {@link Process#ROOT_UID}, {@link Process#SYSTEM_UID}</li>

 * <li>it is the target of the overlay package</li>

 * <li>it has the CHANGE_OVERLAY_PACKAGES permission and the target does not specify an actor</li>

 * <li>it is the actor specified by the overlayable</li>

 * </ul></p>

 *   <li>register overlays

 *   <li>unregister overlays

 *   <li>execute multiple operations in one commitment by calling {@link

 *       OverlayManagerTransaction#commit()}

 * </ul>

 *

 * @see OverlayManagerTransaction

 * @hide

 */

@SystemApi

    /**

     * Pre R a {@link java.lang.SecurityException} would only be thrown by setEnabled APIs (e

     * .g. {@link #setEnabled(String, boolean, UserHandle)}) for a permission error.

     * .g. {@code #setEnabled(String, boolean, UserHandle)}) for a permission error.

     * Since R this no longer holds true, and {@link java.lang.SecurityException} can be

     * thrown for any number of reasons, none of which are exposed to the caller.

     *

    /**

     * Creates a new instance.

     *

     * Updates OverlayManager state; gets information about installed overlay packages.

     * <p>Users of this API must be actors of any overlays they desire to change the state of.

     *

     * <p>An actor is a package responsible for managing the state of overlays targeting

     * overlayables that specify the actor. For example, an actor may enable or disable an overlay

     * or otherwise change its state.

     *

     * <p>Actors are specified as part of the overlayable definition.

     *

     * <pre>{@code

     * <overlayable name="OverlayableResourcesName" actor="overlay://namespace/actorName">

     * }</pre></p>

     *

     * <p>Actors are defined through {@code com.android.server.SystemConfig}. Only system packages

     * can be used. The namespace "android" is reserved for use by AOSP and any "android"

     * definitions must have an implementation on device that fulfill their intended functionality.

     *

     * <pre>{@code

     * <named-actor

     *     namespace="namespace"

     *     name="actorName"

     *     package="com.example.pkg"

     *     />

     * }</pre></p>

     *

     * <p>An actor can manipulate a particular overlay if any of the following is true:

     * <ul>

     * <li>its UID is {@link android.os.Process#ROOT_UID}, {@link android.os.Process#SYSTEM_UID}

     * </li>

     * <li>it is the target of the overlay package</li>

     * <li>it has the CHANGE_OVERLAY_PACKAGES permission and the target does not specify an actor

     * </li>

     * <li>it is the actor specified by the overlayable</li>

     * </ul></p>

     *

     * @param context The current context in which to operate.

     * @param service The backing system service.

     *

     * @hide

     */

    public OverlayManager(Context context, IOverlayManager service) {

    @SuppressLint("ReferencesHidden")

    public OverlayManager(@NonNull Context context, @Nullable IOverlayManager service) {

        mContext = context;

        mService = service;

        mOverlayManagerImpl = new OverlayManagerImpl(context);

    }

    /** @hide */

    public OverlayManager(Context context) {

    @SuppressLint("ReferencesHidden")

    public OverlayManager(@NonNull Context context) {

        this(context, IOverlayManager.Stub.asInterface(

            ServiceManager.getService(Context.OVERLAY_SERVICE)));

    }

     * target package and category are disabled.

     *

     * If a set of overlay packages share the same category, single call to this method is

     * equivalent to multiple calls to {@link #setEnabled(String, boolean, UserHandle)}.

     * equivalent to multiple calls to {@code #setEnabled(String, boolean, UserHandle)}.

     *

     * The caller must pass the actor requirements specified in the class comment.

     *