android-16.0.0_r2/s

/*
 * Copyright (C) 2023 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 com.android.adservices.service.consent;

import android.annotation.NonNull;

import com.android.adservices.service.common.feature.PrivacySandboxFeatureType;
import com.android.adservices.service.ui.enrollment.collection.PrivacySandboxEnrollmentChannelCollection;
import com.android.adservices.service.ui.ux.collection.PrivacySandboxUxCollection;

import com.google.common.collect.ImmutableList;

import java.io.IOException;

/**
 * Interface to handle user's consent related Apis.
 *
 * <p>For Beta the consent is given for all {@link AdServicesApiType} or for none.
 *
 * <p>Currently there are three types of source of truth to store consent data,
 *
 * <ul>
 *   <li>SYSTEM_SERVER_ONLY: Write and read consent from system server only.
 *   <li>PPAPI_ONLY: Write and read consent from PPAPI only.
 *   <li>PPAPI_AND_SYSTEM_SERVER: Write consent to both PPAPI and system server. Read consent from
 *       system server only.
 * </ul>
 *
 * Every source of truth should have its own dedicated storage class that implements the
 * IConsentStorage interface..
 */
public interface IConsentStorage {
    /**
     * Deletes all app consent data and all app data gathered or generated by the Privacy Sandbox.
     *
     * <p>This should be called when the Privacy Sandbox has been disabled.
     *
     * @throws IOException if the operation fails
     */
    void clearAllAppConsentData() throws IOException;

    /**
     * Clear consent data after an app was uninstalled.
     *
     * @param packageName the package name that had been uninstalled.
     * @throws IOException if the operation fails
     */
    void clearConsentForUninstalledApp(@NonNull String packageName) throws IOException;

    /**
     * Clear consent data after an app was uninstalled.
     *
     * @param packageName the package name that had been uninstalled.
     * @param packageUid the package uid that had been uninstalled.
     * @throws IOException if the operation fails
     */
    void clearConsentForUninstalledApp(@NonNull String packageName, int packageUid)
            throws IOException;

    /**
     * Deletes the list of known allowed apps as well as all app data from the Privacy Sandbox.
     *
     * <p>The list of blocked apps is not reset.
     *
     * @throws IOException if the operation fails
     */
    void clearKnownAppsWithConsent() throws IOException;

    /**
     * @return an {@link ImmutableList} of all known apps in the database that have had user consent
     *     revoked
     * @throws IOException if the operation fails
     */
    @NonNull
    ImmutableList<String> getAppsWithRevokedConsent() throws IOException;

    /**
     * Retrieves the consent for all services.
     *
     * <p>To read from PPAPI consent if source of truth is PPAPI. To read from system server consent
     * if source of truth is system server or dual sources.
     *
     * @return AdServicesApiConsent the consent
     * @throws IOException if the operation fails
     */
    @NonNull
    AdServicesApiConsent getConsent(@NonNull AdServicesApiType apiType) throws IOException;

    /**
     * Gets the current privacy sandbox feature.
     *
     * <p>To write to PPAPI if consent source of truth is PPAPI_ONLY or dual sources. To write to
     * system server if consent source of truth is SYSTEM_SERVER_ONLY or dual sources.
     *
     * @return PrivacySandboxFeatureType privacy sandbox feature
     * @throws IOException if the operation fails
     */
    @NonNull
    PrivacySandboxFeatureType getCurrentPrivacySandboxFeature() throws IOException;

    /** Returns current enrollment channel. */
    @NonNull
    PrivacySandboxEnrollmentChannelCollection getEnrollmentChannel(
            @NonNull PrivacySandboxUxCollection ux) throws IOException;

    /**
     * @return an {@link ImmutableList} of all known apps in the database that have not had user
     *     consent revoked
     */
    @NonNull
    ImmutableList<String> getKnownAppsWithConsent() throws IOException;

    /**
     * Returns information whether user interacted with consent manually.
     *
     * @return true if the user interacted with the consent manually, otherwise false.
     */
    int getUserManualInteractionWithConsent() throws IOException;

    /** Returns current UX. */
    @NonNull
    PrivacySandboxUxCollection getUx() throws IOException;

    /** Returns whether the isAdIdEnabled bit is true. */
    boolean isAdIdEnabled() throws IOException;

    /** Returns whether the isAdultAccount bit is true. */
    boolean isAdultAccount() throws IOException;

    /**
     * Returns whether a given application (identified by package name) has had user consent
     * revoked.
     *
     * <p>If the given application is installed but is not found in the datastore, the application
     * is treated as having user consent, and this method returns {@code false}.
     *
     * @throws IllegalArgumentException if the package name is invalid or not found as an installed
     *     application
     * @throws IOException if the operation fails
     */
    boolean isConsentRevokedForApp(@NonNull String packageName)
            throws IllegalArgumentException, IOException;

    /** Returns whether the isEntryPointEnabled bit is true. */
    boolean isEntryPointEnabled() throws IOException;

    /** Returns whether the isU18Account bit is true. */
    boolean isU18Account() throws IOException;

    /**
     * Saves information to the storage that GA UX notification was displayed for the first time to
     * the user.
     */
    void recordGaUxNotificationDisplayed(boolean wasGaUxDisplayed) throws IOException;

    /**
     * Saves information to the storage that notification was displayed for the first time to the
     * user.
     */
    void recordNotificationDisplayed(boolean wasNotificationDisplayed) throws IOException;

    /** Saves information to the storage that user interacted with consent manually. */
    void recordUserManualInteractionWithConsent(int interaction) throws IOException;

    /** Sets the AdIdEnabled bit to storage. */
    void setAdIdEnabled(boolean isAdIdEnabled) throws IOException;

    /** Sets the AdultAccount bit to storage. */
    void setAdultAccount(boolean isAdultAccount) throws IOException;

    /**
     * Sets the consent for this user ID for this API type in storage. If we do not get
     * confirmation that the write was successful, then we throw an exception so that user does not
     * incorrectly think that the consent is updated.
     *
     * @throws IOException if the operation fails
     */
    void setConsent(@NonNull AdServicesApiType apiType, boolean isGiven) throws IOException;

    /**
     * Sets consent for a given installed application, identified by package name.
     *
     * @throws IllegalArgumentException if the package name is invalid or not found as an installed
     *     application
     * @throws IOException if the operation fails
     */
    void setConsentForApp(@NonNull String packageName, boolean isConsentRevoked) throws IOException;

    /**
     * Deletes all app consent data and all app data gathered or generated by the Privacy Sandbox.
     *
     * <p>This should be called when the Privacy Sandbox has been disabled.
     *
     * @throws IOException if the operation fails
     */
    void resetAppsAndBlockedApps() throws IOException;

    /**
     * Deletes the list of known allowed apps as well as all app data from the Privacy Sandbox.
     *
     * <p>The list of blocked apps is not reset.
     *
     * @throws IOException if the operation fails
     */
    void resetApps() throws IOException;

    /**
     * Tries to set consent for a given installed application, identified by package name, if it
     * does not already exist in the datastore, and returns the current consent setting after
     * checking.
     *
     * @return the current consent for the given {@code packageName} after trying to set the {@code
     *     value}
     * @throws IllegalArgumentException if the package name is invalid or not found as an installed
     *     application
     * @throws IOException if the operation fails
     */
    boolean setConsentForAppIfNew(@NonNull String packageName, boolean isConsentRevoked)
            throws IllegalArgumentException, IOException;

    /** Sets the current privacy sandbox feature. */
    void setCurrentPrivacySandboxFeature(@NonNull PrivacySandboxFeatureType featureType)
            throws IOException;

    /** Sets the current enrollment channel to storage. */
    void setEnrollmentChannel(
            @NonNull PrivacySandboxUxCollection ux,
            @NonNull PrivacySandboxEnrollmentChannelCollection channel)
            throws IOException;

    /** Sets the EntryPointEnabled bit to storage . */
    void setEntryPointEnabled(boolean isEntryPointEnabled) throws IOException;

    /** Sets the U18Account bit to storage. */
    void setU18Account(boolean isU18Account) throws IOException;

    /** Sets the U18NotificationDisplayed bit to storage. */
    void setU18NotificationDisplayed(boolean wasU18NotificationDisplayed) throws IOException;

    /** Sets the current UX to storage. */
    void setUx(PrivacySandboxUxCollection ux) throws IOException;

    /**
     * Retrieves if GA UX notification has been displayed.
     *
     * @return true if GA UX Consent Notification was displayed, otherwise false.
     */
    boolean wasGaUxNotificationDisplayed() throws IOException;

    /**
     * Retrieves if notification has been displayed.
     *
     * @return true if Consent Notification was displayed, otherwise false.
     */
    boolean wasNotificationDisplayed() throws IOException;

    /** Returns whether the wasU18NotificationDisplayed bit is true. */
    boolean wasU18NotificationDisplayed() throws IOException;

    /** Returns whether the wasPasNotificationDisplayed bit is true. */
    boolean wasPasNotificationDisplayed() throws IOException;

    /** Records whether the PAS Notification was displayed. */
    void recordPasNotificationDisplayed(boolean wasPasDisplayed) throws IOException;

    /** Set the measurement data reset activity happens based on consent_source_of_truth. */
    void setMeasurementDataReset(boolean isMeasurementDataReset) throws IOException;

    /**
     * Returns whether the measurement data reset activity happens based on consent_source_of_truth.
     */
    boolean isMeasurementDataReset() throws IOException;

    /**
     * Retrieves the PP API default consent.
     *
     * @return true if the default consent is true, false otherwise.
     */
    Boolean getDefaultConsent() throws IOException;

    /**
     * Retrieves the topics default consent.
     *
     * @return true if the topics default consent is true, false otherwise.
     */
    Boolean getTopicsDefaultConsent() throws IOException;

    /**
     * Retrieves the FLEDGE default consent.
     *
     * @return true if the FLEDGE default consent is true, false otherwise.
     */
    Boolean getFledgeDefaultConsent() throws IOException;

    /**
     * Retrieves the measurement default consent.
     *
     * @return true if the measurement default consent is true, false otherwise.
     */
    Boolean getMeasurementDefaultConsent() throws IOException;

    /**
     * Retrieves the default AdId state.
     *
     * @return true if the AdId is enabled by default, false otherwise.
     */
    Boolean getDefaultAdIdState() throws IOException;

    /** Saves the default consent bit to data stores based on source of truth. */
    void recordDefaultConsent(boolean defaultConsent) throws IOException;

    /** Saves the topics default consent bit to data stores based on source of truth. */
    void recordTopicsDefaultConsent(boolean defaultConsent) throws IOException;

    /** Saves the FLEDGE default consent bit to data stores based on source of truth. */
    void recordFledgeDefaultConsent(boolean defaultConsent) throws IOException;

    /** Saves the measurement default consent bit to data stores based on source of truth. */
    void recordMeasurementDefaultConsent(boolean defaultConsent) throws IOException;

    /** Saves the default AdId state bit to data stores based on source of truth. */
    void recordDefaultAdIdState(boolean defaultAdIdState) throws IOException;

    /**
     * Returns whether the measurement data reset activity happens based on consent_source_of_truth.
     */
    Boolean isPaDataReset() throws IOException;

    /** Set the isPaDataReset bit to storage based on consent_source_of_truth. */
    void setPaDataReset(boolean isPaDataReset) throws IOException;
}