content/om/FabricatedOverlay.java

/*
 * Copyright (C) 2021 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.content.om;

import android.annotation.IntDef;
import android.annotation.IntRange;
import android.annotation.NonNull;
import android.annotation.Nullable;
import android.os.FabricatedOverlayInternal;
import android.os.FabricatedOverlayInternalEntry;
import android.os.ParcelFileDescriptor;
import android.text.TextUtils;
import android.util.TypedValue;

import com.android.internal.content.om.OverlayManagerImpl;
import com.android.internal.util.Preconditions;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.util.ArrayList;
import java.util.Objects;

/**
 * FabricatedOverlay describes the content of Fabricated Runtime Resource Overlay (FRRO) that is
 * used to overlay the app's resources. The app should register the {@link FabricatedOverlay}
 * instance in an {@link OverlayManagerTransaction} by calling {@link
 * OverlayManagerTransaction#registerFabricatedOverlay(FabricatedOverlay)}. The FRRO is
 * created once the transaction is committed successfully.
 *
 * <p>The app creates a FabricatedOverlay to describe the how to overlay string, integer, and file
 * type resources. Before creating any frro, please define a target overlayable in {@code
 * res/values/overlayable.xml} that describes what kind of resources can be overlaid, what kind of
 * roles or applications can overlay the resources. Here is an example.
 *
 * <pre>{@code
 * <overlayable name="SignatureOverlayable" actor="overlay://theme">
 *     <!-- The app with the same signature can overlay the below resources -->
 *     <policy type="signature">
 *         <item type="color" name="mycolor" />
 *         <item type="string" name="mystring" />
 *     </policy>
 * </overlayable>
 * }</pre>
 *
 * <p>The overlay must assign the target overlayable name just like the above example by calling
 * {@link #setTargetOverlayable(String)}. Here is an example:
 *
 * <pre>{@code
 * FabricatedOverlay fabricatedOverlay = new FabricatedOverlay("overlay_name",
 *                                                             context.getPackageName());
 * fabricatedOverlay.setTargetOverlayable("SignatureOverlayable")
 * fabricatedOverlay.setResourceValue("mycolor", TypedValue.TYPE_INT_COLOR_ARGB8, Color.White)
 * fabricatedOverlay.setResourceValue("mystring", TypedValue.TYPE_STRING, "Hello")
 * }</pre>
 *
 * <p>The app can create any {@link FabricatedOverlay} instance by calling the following APIs.
 *
 * <ul>
 *   <li>{@link #setTargetOverlayable(String)}
 *   <li>{@link #setResourceValue(String, int, int, String)}
 *   <li>{@link #setResourceValue(String, int, String, String)}
 *   <li>{@link #setResourceValue(String, ParcelFileDescriptor, String)}
 * </ul>
 *
 * @see OverlayManager
 * @see OverlayManagerTransaction
 */
public class FabricatedOverlay {

    /**
     * Retrieves the identifier for this fabricated overlay.
     * @return the overlay identifier
     */
    @NonNull
    public OverlayIdentifier getIdentifier() {
        return new OverlayIdentifier(
                mOverlay.packageName, TextUtils.nullIfEmpty(mOverlay.overlayName));
    }

    /**
     * The builder of Fabricated Runtime Resource Overlays(FRROs).
     *
     * Fabricated overlays are enabled, disabled, and reordered just like normal overlays. The
     * overlayable policies a fabricated overlay fulfills are the same policies the creator of the
     * overlay fulfill. For example, a fabricated overlay created by a platform signed package on
     * the system partition would fulfil the {@code system} and {@code signature} policies.
     *
     * The owner of a fabricated overlay is the UID that created it. Overlays commit to the overlay
     * manager persist across reboots. When the UID is uninstalled, its fabricated overlays are
     * wiped.
     *
     * Processes with {@code android.Manifest.permission#CHANGE_OVERLAY_PACKAGES} can manage normal
     * overlays and fabricated overlays.
     *
     * @see FabricatedOverlay
     * @see OverlayManagerTransaction.Builder#registerFabricatedOverlay(FabricatedOverlay)
     * @hide
     */
    public static final class Builder {
        private final String mOwningPackage;
        private final String mName;
        private final String mTargetPackage;
        private String mTargetOverlayable = "";
        private final ArrayList<FabricatedOverlayInternalEntry> mEntries = new ArrayList<>();

        /**
         * Constructs a build for a fabricated overlay.
         *
         * @param owningPackage the name of the package that owns the fabricated overlay (must
         *                      be a package name of this UID).
         * @param name a name used to uniquely identify the fabricated overlay owned by
         *             {@param owningPackageName}
         * @param targetPackage the name of the package to overlay
         */
        public Builder(@NonNull String owningPackage, @NonNull String name,
                @NonNull String targetPackage) {
            Preconditions.checkStringNotEmpty(owningPackage,
                    "'owningPackage' must not be empty nor null");
            Preconditions.checkStringNotEmpty(name,
                    "'name'' must not be empty nor null");
            Preconditions.checkStringNotEmpty(targetPackage,
                    "'targetPackage' must not be empty nor null");

            mOwningPackage = owningPackage;
            mName = name;
            mTargetPackage = targetPackage;
        }

        /**
         * Sets the name of the target overlayable to be overlaid.
         *
         * <p>The target package defines may define several overlayables. The
         * {@link FabricatedOverlay} should specify which overlayable to be overlaid.
         *
         * <p>The target overlayable should be defined in {@code <overlayable>} and pass the value
         * of its {@code name} attribute as the parameter.
         *
         * @param targetOverlayable is a name of the overlayable resources set
         * @hide
         */
        @NonNull
        public Builder setTargetOverlayable(@Nullable String targetOverlayable) {
            mTargetOverlayable = TextUtils.emptyIfNull(targetOverlayable);
            return this;
        }

        /**
         * Sets the value of the fabricated overlay for the integer-like types.
         *
         * @param resourceName name of the target resource to overlay (in the form
         *     [package]:type/entry)
         * @param dataType the data type of the new value
         * @param value the unsigned 32 bit integer representing the new value
         * @return the builder itself
         * @see #setResourceValue(String, int, int, String)
         * @see android.util.TypedValue#TYPE_INT_COLOR_ARGB8 android.util.TypedValue#type
         * @deprecated Framework should use {@link FabricatedOverlay#setResourceValue(String, int,
                       int, String)} instead.
         * @hide
         */
        @Deprecated(since = "Please use FabricatedOverlay#setResourceValue instead")
        @NonNull
        public Builder setResourceValue(
                @NonNull String resourceName,
                @IntRange(from = TypedValue.TYPE_FIRST_INT, to = TypedValue.TYPE_LAST_INT)
                        int dataType,
                int value) {
            return setResourceValue(resourceName, dataType, value, null /* configuration */);
        }

        /**
         * Sets the value of the fabricated overlay for the integer-like types with the
         * configuration.
         *
         * @param resourceName name of the target resource to overlay (in the form
         *     [package]:type/entry)
         * @param dataType the data type of the new value
         * @param value the unsigned 32 bit integer representing the new value
         * @param configuration The string representation of the config this overlay is enabled for
         * @return the builder itself
         * @see android.util.TypedValue#TYPE_INT_COLOR_ARGB8 android.util.TypedValue#type
         * @deprecated Framework should use {@link FabricatedOverlay#setResourceValue(String, int,
                       int, String)} instead.
         * @hide
         */
        @Deprecated(since = "Please use FabricatedOverlay#setResourceValue instead")
        @NonNull
        public Builder setResourceValue(
                @NonNull String resourceName,
                @IntRange(from = TypedValue.TYPE_FIRST_INT, to = TypedValue.TYPE_LAST_INT)
                        int dataType,
                int value,
                @Nullable String configuration) {
            ensureValidResourceName(resourceName);
            mEntries.add(generateFabricatedOverlayInternalEntry(resourceName, dataType, value,
                    configuration));
            return this;
        }

        /**
         * Sets the value of the fabricated overlay for the string-like type.
         *
         * @param resourceName name of the target resource to overlay (in the form
         *     [package]:type/entry)
         * @param dataType the data type of the new value
         * @param value the string representing the new value
         * @return the builder itself
         * @see android.util.TypedValue#TYPE_STRING android.util.TypedValue#type
         * @deprecated Framework should use {@link FabricatedOverlay#setResourceValue(String, int,
                       String, String)} instead.
         * @hide
         */
        @Deprecated(since = "Please use FabricatedOverlay#setResourceValue instead")
        @NonNull
        public Builder setResourceValue(
                @NonNull String resourceName,
                @StringTypeOverlayResource int dataType,
                @NonNull String value) {
            return setResourceValue(resourceName, dataType, value, null /* configuration */);
        }

        /**
         * Sets the value of the fabricated overlay for the string-like type with the configuration.
         *
         * @param resourceName name of the target resource to overlay (in the form
         *     [package]:type/entry)
         * @param dataType the data type of the new value
         * @param value the string representing the new value
         * @param configuration The string representation of the config this overlay is enabled for
         * @return the builder itself
         * @see android.util.TypedValue#TYPE_STRING android.util.TypedValue#type
         * @deprecated Framework should use {@link FabricatedOverlay#setResourceValue(String, int,
                       String, String)} instead.
         * @hide
         */
        @Deprecated(since = "Please use FabricatedOverlay#setResourceValue instead")
        @NonNull
        public Builder setResourceValue(
                @NonNull String resourceName,
                @StringTypeOverlayResource int dataType,
                @NonNull String value,
                @Nullable String configuration) {
            ensureValidResourceName(resourceName);
            mEntries.add(generateFabricatedOverlayInternalEntry(resourceName, dataType, value,
                    configuration));
            return this;
        }

        /**
         * Sets the value of the fabricated overlay for the file descriptor type.
         *
         * @param resourceName name of the target resource to overlay (in the form
         *     [package]:type/entry)
         * @param value the file descriptor whose contents are the value of the frro
         * @param configuration The string representation of the config this overlay is enabled for
         * @return the builder itself
         * @deprecated Framework should use {@link FabricatedOverlay#setResourceValue(String,
                       ParcelFileDescriptor, String)} instead.
         * @hide
         */
        @Deprecated(since = "Please use FabricatedOverlay#setResourceValue instead")
        @NonNull
        public Builder setResourceValue(
                @NonNull String resourceName,
                @NonNull ParcelFileDescriptor value,
                @Nullable String configuration) {
            ensureValidResourceName(resourceName);
            mEntries.add(
                    generateFabricatedOverlayInternalEntry(resourceName, value, configuration));
            return this;
        }

        /**
         * Builds an immutable fabricated overlay.
         *
         * @return the fabricated overlay
         * @hide
         */
        @NonNull
        public FabricatedOverlay build() {
            return new FabricatedOverlay(
                    generateFabricatedOverlayInternal(mOwningPackage, mName, mTargetPackage,
                            mTargetOverlayable, mEntries));
        }
    }

    private static FabricatedOverlayInternal generateFabricatedOverlayInternal(
            @NonNull String owningPackage, @NonNull String overlayName,
            @NonNull String targetPackageName, @Nullable String targetOverlayable,
            @NonNull ArrayList<FabricatedOverlayInternalEntry> entries) {
        final FabricatedOverlayInternal overlay = new FabricatedOverlayInternal();
        overlay.packageName = owningPackage;
        overlay.overlayName = overlayName;
        overlay.targetPackageName = targetPackageName;
        overlay.targetOverlayable = TextUtils.emptyIfNull(targetOverlayable);
        overlay.entries = new ArrayList<>();
        overlay.entries.addAll(entries);
        return overlay;
    }

    final FabricatedOverlayInternal mOverlay;
    private FabricatedOverlay(FabricatedOverlayInternal overlay) {
        mOverlay = overlay;
    }

    /**
     * Create a fabricated overlay to overlay on the specified package.
     *
     * @param overlayName a name used to uniquely identify the fabricated overlay owned by the
     *                   caller itself.
     * @param targetPackage the name of the package to be overlaid
     */
    public FabricatedOverlay(@NonNull String overlayName, @NonNull String targetPackage) {
        this(generateFabricatedOverlayInternal(
                "" /* owningPackage, The package name is filled commitment */,
                OverlayManagerImpl.checkOverlayNameValid(overlayName),
                Preconditions.checkStringNotEmpty(targetPackage,
                        "'targetPackage' must not be empty nor null"),
                null /* targetOverlayable */,
                new ArrayList<>()));
    }

    /**
     * Set the target overlayable name of the overlay
     *
     * The target package defines may define several overlayables. The {@link FabricatedOverlay}
     * should specify which overlayable to be overlaid.
     *
     * @param targetOverlayable the overlayable name defined in target package.
     */
    public void setTargetOverlayable(@Nullable String targetOverlayable) {
        mOverlay.targetOverlayable = TextUtils.emptyIfNull(targetOverlayable);
    }

    /**
     * Return the target overlayable name of the overlay
     *
     * The target package defines may define several overlayables. The {@link FabricatedOverlay}
     * should specify which overlayable to be overlaid.
     *
     * @return the target overlayable name.
     * @hide
     */
    @Nullable
    public String getTargetOverlayable() {
        return mOverlay.targetOverlayable;
    }

    /**
     * Ensure the resource name is in the form [package]:type/entry.
     *
     * @param name name of the target resource to overlay (in the form [package]:type/entry)
     * @return the valid name
     */
    private static String ensureValidResourceName(@NonNull String name) {
        Objects.requireNonNull(name);
        final int slashIndex = name.indexOf('/'); /* must contain '/' */
        final int colonIndex = name.indexOf(':'); /* ':' should before '/' if ':' exist */

        // The minimum length of resource type is "id".
        Preconditions.checkArgument(
                slashIndex >= 0 /* It must contain the type name */
                        && colonIndex != 0 /* 0 means the package name is empty */
                        && (slashIndex - colonIndex) > 2 /* The shortest length of type is "id" */,
                "\"%s\" is invalid resource name",
                name);
        return name;
    }

    @NonNull
    private static FabricatedOverlayInternalEntry generateFabricatedOverlayInternalEntry(
            @NonNull String resourceName,
            @IntRange(from = TypedValue.TYPE_FIRST_INT, to = TypedValue.TYPE_LAST_INT) int dataType,
            int value, @Nullable String configuration) {
        final FabricatedOverlayInternalEntry entry = new FabricatedOverlayInternalEntry();
        entry.resourceName = resourceName;
        entry.dataType =
                Preconditions.checkArgumentInRange(
                        dataType,
                        TypedValue.TYPE_FIRST_INT,
                        TypedValue.TYPE_LAST_INT,
                        "dataType");
        entry.data = value;
        entry.configuration = configuration;
        return entry;
    }

    @NonNull
    private static FabricatedOverlayInternalEntry generateFabricatedOverlayInternalEntry(
            @NonNull String resourceName, @StringTypeOverlayResource int dataType,
            @NonNull String value, @Nullable String configuration) {
        final FabricatedOverlayInternalEntry entry = new FabricatedOverlayInternalEntry();
        entry.resourceName = resourceName;
        entry.dataType =
                Preconditions.checkArgumentInRange(
                        dataType, TypedValue.TYPE_STRING, TypedValue.TYPE_FRACTION, "dataType");
        entry.stringData = Objects.requireNonNull(value);
        entry.configuration = configuration;
        return entry;
    }

    @NonNull
    private static FabricatedOverlayInternalEntry generateFabricatedOverlayInternalEntry(
            @NonNull String resourceName, @NonNull ParcelFileDescriptor parcelFileDescriptor,
            @Nullable String configuration) {
        final FabricatedOverlayInternalEntry entry = new FabricatedOverlayInternalEntry();
        entry.resourceName = resourceName;
        entry.binaryData = Objects.requireNonNull(parcelFileDescriptor);
        entry.configuration = configuration;
        return entry;
    }

    /**
     * Sets the resource value in the fabricated overlay for the integer-like types with the
     * configuration.
     *
     * @param resourceName name of the target resource to overlay (in the form
     *     [package]:type/entry)
     * @param dataType the data type of the new value
     * @param value the integer representing the new value
     * @param configuration The string representation of the config this overlay is enabled for
     * @see android.util.TypedValue#TYPE_INT_COLOR_ARGB8 android.util.TypedValue#type
     */
    @NonNull
    public void setResourceValue(
            @NonNull String resourceName,
            @IntRange(from = TypedValue.TYPE_FIRST_INT, to = TypedValue.TYPE_LAST_INT) int dataType,
            int value,
            @Nullable String configuration) {
        ensureValidResourceName(resourceName);
        mOverlay.entries.add(generateFabricatedOverlayInternalEntry(resourceName, dataType, value,
                configuration));
    }

    /** @hide */
    @IntDef(
            prefix = {"OVERLAY_TYPE"},
            value = {
                    TypedValue.TYPE_STRING,
            })
    @Retention(RetentionPolicy.SOURCE)
    public @interface StringTypeOverlayResource {}

    /**
     * Sets the resource value in the fabricated overlay for the string-like type with the
     * configuration.
     *
     * @param resourceName name of the target resource to overlay (in the form
     *     [package]:type/entry)
     * @param dataType the data type of the new value
     * @param value the string representing the new value
     * @param configuration The string representation of the config this overlay is enabled for
     * @see android.util.TypedValue#TYPE_STRING android.util.TypedValue#type
     */
    @NonNull
    public void setResourceValue(
            @NonNull String resourceName,
            @StringTypeOverlayResource int dataType,
            @NonNull String value,
            @Nullable String configuration) {
        ensureValidResourceName(resourceName);
        mOverlay.entries.add(generateFabricatedOverlayInternalEntry(resourceName, dataType, value,
                configuration));
    }

    /**
     * Sets the resource value in the fabricated overlay for the file descriptor type with the
     * configuration.
     *
     * @param resourceName name of the target resource to overlay (in the form
     *     [package]:type/entry)
     * @param value the file descriptor whose contents are the value of the frro
     * @param configuration The string representation of the config this overlay is enabled for
     */
    @NonNull
    public void setResourceValue(
            @NonNull String resourceName,
            @NonNull ParcelFileDescriptor value,
            @Nullable String configuration) {
        ensureValidResourceName(resourceName);
        mOverlay.entries.add(
                generateFabricatedOverlayInternalEntry(resourceName, value, configuration));
    }
}