Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit ddb2e801 authored by Kenneth Ford's avatar Kenneth Ford
Browse files

Promote DeviceStateManager to System API and update DeviceStateManager API's 

Promote DeviceStateManager to System API
and add updated DeviceState property API's, as well
as DeviceStateManager callback API's to return DeviceState
objects instead of just integer identifiers.

Deprecated the previous constructor and
flag based API's on DeviceState

Bug: 293636629
Test: DeviceStateManagerTests
Change-Id: I564a13988f6d5fe952b2877a0b45ce8a039fe966
parent 2f0c5f20

AconfigFlags.bp

+15 −0
Original line number Diff line number Diff line
@@ -32,6 +32,7 @@ aconfig_srcjars = [ 
    ":android.credentials.flags-aconfig-java{.generated_srcjars}",

    ":android.database.sqlite-aconfig-java{.generated_srcjars}",

    ":android.hardware.biometrics.flags-aconfig-java{.generated_srcjars}",

    ":android.hardware.devicestate.feature.flags-aconfig-java{.generated_srcjars}",

    ":android.hardware.flags-aconfig-java{.generated_srcjars}",

    ":android.hardware.radio.flags-aconfig-java{.generated_srcjars}",

    ":android.hardware.usb.flags-aconfig-java{.generated_srcjars}",
@@ -108,6 +109,7 @@ stubs_defaults { 
        "android.credentials.flags-aconfig",

        "android.database.sqlite-aconfig",

        "android.hardware.biometrics.flags-aconfig",

        "android.hardware.devicestate.feature.flags-aconfig",

        "android.hardware.flags-aconfig",

        "android.hardware.radio.flags-aconfig",

        "android.hardware.usb.flags-aconfig",
@@ -227,6 +229,19 @@ java_aconfig_library { 
    defaults: ["framework-minus-apex-aconfig-java-defaults"],

}



// DeviceStateManager

aconfig_declarations {

    name: "android.hardware.devicestate.feature.flags-aconfig",

    package: "android.hardware.devicestate.feature.flags",

    srcs: ["core/java/android/hardware/devicestate/feature/*.aconfig"],

}



java_aconfig_library {

    name: "android.hardware.devicestate.feature.flags-aconfig-java",

    aconfig_declarations: "android.hardware.devicestate.feature.flags-aconfig",

    defaults: ["framework-minus-apex-aconfig-java-defaults"],

}



// Input

aconfig_declarations {

    name: "com.android.hardware.input.input-aconfig",

core/api/system-current.txt

+33 −0
Original line number Diff line number Diff line
@@ -4835,6 +4835,39 @@ package android.hardware.camera2.params { 














}



























package android.hardware.devicestate {

























  @FlaggedApi("android.hardware.devicestate.feature.flags.device_state_property_api") public final class DeviceState {













    method @IntRange(from=0x0) public int getIdentifier();













    method @NonNull public String getName();













    method public boolean hasProperties(@NonNull int...);













    method public boolean hasProperty(int);













    field public static final int PROPERTY_EMULATED_ONLY = 10; // 0xa













    field public static final int PROPERTY_EXTENDED_DEVICE_STATE_EXTERNAL_DISPLAY = 15; // 0xf













    field public static final int PROPERTY_FEATURE_DUAL_DISPLAY_INTERNAL_DEFAULT = 17; // 0x11













    field public static final int PROPERTY_FEATURE_REAR_DISPLAY = 16; // 0x10













    field public static final int PROPERTY_FOLDABLE_DISPLAY_CONFIGURATION_INNER_PRIMARY = 12; // 0xc













    field public static final int PROPERTY_FOLDABLE_DISPLAY_CONFIGURATION_OUTER_PRIMARY = 11; // 0xb













    field public static final int PROPERTY_FOLDABLE_HARDWARE_CONFIGURATION_FOLD_IN_CLOSED = 1; // 0x1













    field public static final int PROPERTY_FOLDABLE_HARDWARE_CONFIGURATION_FOLD_IN_HALF_OPEN = 2; // 0x2













    field public static final int PROPERTY_FOLDABLE_HARDWARE_CONFIGURATION_FOLD_IN_OPEN = 3; // 0x3













    field public static final int PROPERTY_POWER_CONFIGURATION_TRIGGER_SLEEP = 13; // 0xd













    field public static final int PROPERTY_POWER_CONFIGURATION_TRIGGER_WAKE = 14; // 0xe













  }

























  @FlaggedApi("android.hardware.devicestate.feature.flags.device_state_property_api") public final class DeviceStateManager {













    method @NonNull public java.util.List<android.hardware.devicestate.DeviceState> getSupportedDeviceStates();













    method public void registerCallback(@NonNull java.util.concurrent.Executor, @NonNull android.hardware.devicestate.DeviceStateManager.DeviceStateCallback);













    method public void unregisterCallback(@NonNull android.hardware.devicestate.DeviceStateManager.DeviceStateCallback);













  }

























  public static interface DeviceStateManager.DeviceStateCallback {













    method public default void onDeviceStateChanged(@NonNull android.hardware.devicestate.DeviceState);













    method public default void onSupportedStatesChanged(@NonNull java.util.List<android.hardware.devicestate.DeviceState>);













  }

























}



























package android.hardware.display {





























  public final class AmbientBrightnessDayStats implements android.os.Parcelable {

























core/api/test-current.txt



+13
−9




























Original line number
Diff line number
Diff line








@@ -1620,22 +1620,26 @@ package android.hardware.camera2.params {





























package android.hardware.devicestate {





























  public final class DeviceStateManager {













  @FlaggedApi("android.hardware.devicestate.feature.flags.device_state_property_api") public final class DeviceState {













    ctor @Deprecated public DeviceState(@IntRange(from=android.hardware.devicestate.DeviceStateManager.MINIMUM_DEVICE_STATE_IDENTIFIER, to=android.hardware.devicestate.DeviceStateManager.MAXIMUM_DEVICE_STATE_IDENTIFIER) int, @NonNull String, int);













    ctor public DeviceState(@IntRange(from=android.hardware.devicestate.DeviceStateManager.MINIMUM_DEVICE_STATE_IDENTIFIER, to=android.hardware.devicestate.DeviceStateManager.MAXIMUM_DEVICE_STATE_IDENTIFIER) int, @NonNull String, @NonNull java.util.Set<java.lang.Integer>);













    field public static final int PROPERTY_POLICY_AVAILABLE_FOR_APP_REQUEST = 8; // 0x8













  }



























  @FlaggedApi("android.hardware.devicestate.feature.flags.device_state_property_api") public final class DeviceStateManager {















    method @RequiresPermission(android.Manifest.permission.CONTROL_DEVICE_STATE) public void cancelBaseStateOverride();















    method @RequiresPermission(value=android.Manifest.permission.CONTROL_DEVICE_STATE, conditional=true) public void cancelStateRequest();













    method @NonNull public int[] getSupportedStates();













    method public void registerCallback(@NonNull java.util.concurrent.Executor, @NonNull android.hardware.devicestate.DeviceStateManager.DeviceStateCallback);













    method @Deprecated @NonNull public int[] getSupportedStates();















    method @RequiresPermission(android.Manifest.permission.CONTROL_DEVICE_STATE) public void requestBaseStateOverride(@NonNull android.hardware.devicestate.DeviceStateRequest, @Nullable java.util.concurrent.Executor, @Nullable android.hardware.devicestate.DeviceStateRequest.Callback);















    method @RequiresPermission(value=android.Manifest.permission.CONTROL_DEVICE_STATE, conditional=true) public void requestState(@NonNull android.hardware.devicestate.DeviceStateRequest, @Nullable java.util.concurrent.Executor, @Nullable android.hardware.devicestate.DeviceStateRequest.Callback);













    method public void unregisterCallback(@NonNull android.hardware.devicestate.DeviceStateManager.DeviceStateCallback);













    field public static final int MAXIMUM_DEVICE_STATE = 255; // 0xff













    field public static final int MINIMUM_DEVICE_STATE = 0; // 0x0













    field public static final int MAXIMUM_DEVICE_STATE_IDENTIFIER = 10000; // 0x2710













    field public static final int MINIMUM_DEVICE_STATE_IDENTIFIER = 0; // 0x0















  }































  public static interface DeviceStateManager.DeviceStateCallback {













    method public default void onBaseStateChanged(int);













    method public void onStateChanged(int);













    method public default void onSupportedStatesChanged(@NonNull int[]);













    method @Deprecated public default void onBaseStateChanged(int);













    method @Deprecated public void onStateChanged(int);













    method @Deprecated public default void onSupportedStatesChanged(@NonNull int[]);















  }































  public final class DeviceStateRequest {

































core/java/android/hardware/devicestate/DeviceState.java



+243
−12




























Original line number
Diff line number
Diff line








@@ -16,18 +16,25 @@





























package android.hardware.devicestate;





























import static android.hardware.devicestate.DeviceStateManager.MAXIMUM_DEVICE_STATE;













import static android.hardware.devicestate.DeviceStateManager.MINIMUM_DEVICE_STATE;













import static android.hardware.devicestate.DeviceStateManager.MAXIMUM_DEVICE_STATE_IDENTIFIER;













import static android.hardware.devicestate.DeviceStateManager.MINIMUM_DEVICE_STATE_IDENTIFIER;





























import android.annotation.FlaggedApi;















import android.annotation.IntDef;















import android.annotation.IntRange;















import android.annotation.NonNull;













import android.annotation.SystemApi;













import android.annotation.TestApi;































import com.android.internal.util.Preconditions;





























import java.lang.annotation.ElementType;















import java.lang.annotation.Retention;















import java.lang.annotation.RetentionPolicy;













import java.lang.annotation.Target;













import java.util.Collections;















import java.util.Objects;













import java.util.Set;































/**















 * A state of the device defined by the {@link DeviceStateProvider} and managed by the









@@ -37,21 +44,29 @@ import java.util.Objects;













 * state of the system. This is useful for variable-state devices, like foldable or rollable















 * devices, that can be configured by users into differing hardware states, which each may have a















 * different expected use case.













 * @hide















 *













 * @hide















 * @see DeviceStateManager















 */













@SystemApi













@FlaggedApi(android.hardware.devicestate.feature.flags.Flags.FLAG_DEVICE_STATE_PROPERTY_API)















public final class DeviceState {















    /**















     * Flag that indicates override requests should be cancelled when this device state becomes the















     * base device state.













     * @hide













     * @deprecated use {@link #PROPERTY_POLICY_CANCEL_OVERRIDE_REQUESTS}















     */













    @Deprecated















    public static final int FLAG_CANCEL_OVERRIDE_REQUESTS = 1 << 0;































    /**















     * Flag that indicates this device state is inaccessible for applications to be placed in. This













     * could be a device-state where the {@link DEFAULT_DISPLAY} is not enabled.













     * could be a device-state where the {@link Display#DEFAULT_DISPLAY} is not enabled.













     * @hide













     * @deprecated use {@link #PROPERTY_APP_INACCESSIBLE}















     */













    @Deprecated















    public static final int FLAG_APP_INACCESSIBLE = 1 << 1;































    /**









@@ -60,7 +75,10 @@ public final class DeviceState {













     * through emulation and have no physical configuration to match.















     *















     * This flag indicates that the corresponding state can only be entered through emulation.













     * @hide













     * @deprecated use {@link #PROPERTY_EMULATED_ONLY}















     */













    @Deprecated















    public static final int FLAG_EMULATED_ONLY = 1 << 2;































    /**









@@ -68,19 +86,28 @@ public final class DeviceState {













     * requesting app is no longer on top. The app is considered not on top when (1) the top















     * activity in the system is from a different app, (2) the device is in sleep mode, or















     * (3) the keyguard shows up.













     * @hide













     * @deprecated use {@link #PROPERTY_POLICY_CANCEL_WHEN_REQUESTER_NOT_ON_TOP}















     */













    @Deprecated















    public static final int FLAG_CANCEL_WHEN_REQUESTER_NOT_ON_TOP = 1 << 3;































    /**















     * This flag indicates that the corresponding state should be disabled when the device is















     * overheating and reaching the critical status.













     * @hide













     * @deprecated use {@link #PROPERTY_POLICY_UNSUPPORTED_WHEN_THERMAL_STATUS_CRITICAL}















     */













    @Deprecated















    public static final int FLAG_UNSUPPORTED_WHEN_THERMAL_STATUS_CRITICAL = 1 << 4;































    /**















     * This flag indicates that the corresponding state should be disabled when power save mode















     * is enabled.













     * @hide













     * @deprecated use {@link #PROPERTY_POLICY_UNSUPPORTED_WHEN_POWER_SAVE_MODE}















     */













    @Deprecated















    public static final int FLAG_UNSUPPORTED_WHEN_POWER_SAVE_MODE = 1 << 5;































    /** @hide */









@@ -92,11 +119,157 @@ public final class DeviceState {













            FLAG_UNSUPPORTED_WHEN_THERMAL_STATUS_CRITICAL,















            FLAG_UNSUPPORTED_WHEN_POWER_SAVE_MODE















    })













    @Deprecated















    @Retention(RetentionPolicy.SOURCE)















    public @interface DeviceStateFlags {}





























    /**













     * Property that indicates that a fold-in style foldable device is currently in a fully closed













     * configuration.













     */













    public static final int PROPERTY_FOLDABLE_HARDWARE_CONFIGURATION_FOLD_IN_CLOSED = 1;



























    /**













     * Property that indicates that a fold-in style foldable device is currently in a half-opened













     * configuration. This signifies that the device's hinge is positioned somewhere around 90













     * degrees. Checking for display configuration properties as well can provide information













     * on which display is currently active.













     */













    public static final int PROPERTY_FOLDABLE_HARDWARE_CONFIGURATION_FOLD_IN_HALF_OPEN = 2;



























    /**













     * Property that indicates that a fold-in style foldable device is currently in a fully open













     * configuration.













     */













    public static final int PROPERTY_FOLDABLE_HARDWARE_CONFIGURATION_FOLD_IN_OPEN = 3;



























    /**













     * Property that indicates override requests should be cancelled when the device is physically













     * put into this state.













     * @hide













     */













    public static final int PROPERTY_POLICY_CANCEL_OVERRIDE_REQUESTS = 4;



























    /**













     * This property indicates that the corresponding state should be automatically canceled when













     * the requesting app is no longer on top. The app is considered not on top when (1) the top













     * activity in the system is from a different app, (2) the device is in sleep mode, or













     * (3) the keyguard shows up.













     * @hide













     */













    public static final int PROPERTY_POLICY_CANCEL_WHEN_REQUESTER_NOT_ON_TOP = 5;



























    /**













     * This property indicates that the corresponding state should be disabled when the device is













     * overheating and reaching the critical status.













     * @hide













     */













    public static final int PROPERTY_POLICY_UNSUPPORTED_WHEN_THERMAL_STATUS_CRITICAL = 6;



























    /**













     * This property indicates that the corresponding state should be disabled when power save mode













     * is enabled.













     * @hide













     */













    public static final int PROPERTY_POLICY_UNSUPPORTED_WHEN_POWER_SAVE_MODE = 7;



























    /**













     * This property denotes that this state is available for applications to request and the system













     * server should deny any request that comes from a process that does not hold the













     * CONTROL_DEVICE_STATE permission if it is requesting a state that does not have this property













     * on it.













     * @hide













     */













    @TestApi













    public static final int PROPERTY_POLICY_AVAILABLE_FOR_APP_REQUEST = 8;



























    /**













     * Property that indicates this device state is inaccessible for applications to be made













     * visible to the user. This could be a device-state where the {@link Display#DEFAULT_DISPLAY}













     * is not enabled.













     * @hide













     */













    public static final int PROPERTY_APP_INACCESSIBLE = 9;



























    /**













     * This property indidcates that this state can only be entered through emulation and has no













     * physical configuration to match.













     */













    public static final int PROPERTY_EMULATED_ONLY = 10;



























    /**













     * Property that indicates that the outer display area of a foldable device is currently the













     * primary display area.













     *













     * Note: This does not necessarily mean that the outer display area is the













     * @link Display#DEFAULT_DISPLAY}.













     */













    public static final int PROPERTY_FOLDABLE_DISPLAY_CONFIGURATION_OUTER_PRIMARY = 11;



























    /**













     * Property that indicates that the inner display area of a foldable device is currently the













     * primary display area.













     *













     * Note: This does not necessarily mean that the inner display area is the













     * {@link Display#DEFAULT_DISPLAY}.













     */













    public static final int PROPERTY_FOLDABLE_DISPLAY_CONFIGURATION_INNER_PRIMARY = 12;



























    /**













     * Property that indicates that this device state will attempt to trigger the device to go to













     * sleep.













     */













    public static final int PROPERTY_POWER_CONFIGURATION_TRIGGER_SLEEP = 13;



























    /**













     * Property that indicates that this device state will attempt to trigger the device to wake up.













     */













    public static final int PROPERTY_POWER_CONFIGURATION_TRIGGER_WAKE = 14;



























    /**













     * Property that indicates that an external display has been connected to the device. Specifics













     * around display mode or properties around the display should be gathered through













     * {@link android.hardware.display.DisplayManager}













     */













    public static final int PROPERTY_EXTENDED_DEVICE_STATE_EXTERNAL_DISPLAY = 15;













    /**













     * Property that indicates that this state corresponds to the device state for rear display













     * mode. This means that the active display is facing the same direction as the rear camera.













     */













    public static final int PROPERTY_FEATURE_REAR_DISPLAY = 16;



























    /**













     * Property that indicates that this state corresponds to the device state where both displays













     * on a foldable are active, with the internal display being the default display.













     */













    public static final int PROPERTY_FEATURE_DUAL_DISPLAY_INTERNAL_DEFAULT = 17;



























    /** @hide */













    @IntDef(prefix = {"PROPERTY_"}, flag = true, value = {













            PROPERTY_FOLDABLE_HARDWARE_CONFIGURATION_FOLD_IN_CLOSED,













            PROPERTY_FOLDABLE_HARDWARE_CONFIGURATION_FOLD_IN_HALF_OPEN,













            PROPERTY_FOLDABLE_HARDWARE_CONFIGURATION_FOLD_IN_OPEN,













            PROPERTY_POLICY_CANCEL_OVERRIDE_REQUESTS,













            PROPERTY_POLICY_CANCEL_WHEN_REQUESTER_NOT_ON_TOP,













            PROPERTY_POLICY_UNSUPPORTED_WHEN_THERMAL_STATUS_CRITICAL,













            PROPERTY_POLICY_UNSUPPORTED_WHEN_POWER_SAVE_MODE,













            PROPERTY_POLICY_AVAILABLE_FOR_APP_REQUEST,













            PROPERTY_APP_INACCESSIBLE,













            PROPERTY_EMULATED_ONLY,













            PROPERTY_FOLDABLE_DISPLAY_CONFIGURATION_OUTER_PRIMARY,













            PROPERTY_FOLDABLE_DISPLAY_CONFIGURATION_INNER_PRIMARY,













            PROPERTY_POWER_CONFIGURATION_TRIGGER_SLEEP,













            PROPERTY_POWER_CONFIGURATION_TRIGGER_WAKE,













            PROPERTY_EXTENDED_DEVICE_STATE_EXTERNAL_DISPLAY,













            PROPERTY_FEATURE_REAR_DISPLAY,













            PROPERTY_FEATURE_DUAL_DISPLAY_INTERNAL_DEFAULT













    })













    @Retention(RetentionPolicy.SOURCE)













    @Target({ElementType.TYPE_PARAMETER, ElementType.TYPE_USE})













    public @interface DeviceStateProperties {}





























    /** Unique identifier for the device state. */













    @IntRange(from = MINIMUM_DEVICE_STATE, to = MAXIMUM_DEVICE_STATE)













    @IntRange(from = MINIMUM_DEVICE_STATE_IDENTIFIER, to = MAXIMUM_DEVICE_STATE_IDENTIFIER)















    private final int mIdentifier;































    /** String description of the device state. */









@@ -106,20 +279,49 @@ public final class DeviceState {













    @DeviceStateFlags















    private final int mFlags;





























    private final Set<@DeviceStateProperties Integer> mProperties;



























    /**













     * @deprecated Deprecated in favor of {@link #DeviceState(int, String, Set)}













     * @hide













     */













    // TODO(b/325124054): Make non-default and remove deprecated callback methods.













    @TestApi













    @Deprecated















    public DeviceState(













            @IntRange(from = MINIMUM_DEVICE_STATE, to = MAXIMUM_DEVICE_STATE) int identifier,













            @IntRange(from = MINIMUM_DEVICE_STATE_IDENTIFIER, to =













                    MAXIMUM_DEVICE_STATE_IDENTIFIER) int identifier,















            @NonNull String name,















            @DeviceStateFlags int flags) {













        Preconditions.checkArgumentInRange(identifier, MINIMUM_DEVICE_STATE, MAXIMUM_DEVICE_STATE,













        Preconditions.checkArgumentInRange(identifier, MINIMUM_DEVICE_STATE_IDENTIFIER,













                MAXIMUM_DEVICE_STATE_IDENTIFIER,















                "identifier");































        mIdentifier = identifier;















        mName = name;















        mFlags = flags;













        mProperties = Collections.emptySet();













    }



























    /** @hide */













    @TestApi













    public DeviceState(













            @IntRange(from = MINIMUM_DEVICE_STATE_IDENTIFIER, to =













                    MAXIMUM_DEVICE_STATE_IDENTIFIER) int identifier,













            @NonNull String name,













            @NonNull Set<@DeviceStateProperties Integer> properties) {













        Preconditions.checkArgumentInRange(identifier, MINIMUM_DEVICE_STATE_IDENTIFIER,













                MAXIMUM_DEVICE_STATE_IDENTIFIER,













                "identifier");



























        mIdentifier = identifier;













        mName = name;













        mProperties = Set.copyOf(properties);













        mFlags = 0;















    }































    /** Returns the unique identifier for the device state. */













    @IntRange(from = MINIMUM_DEVICE_STATE, to = MAXIMUM_DEVICE_STATE)













    @IntRange(from = MINIMUM_DEVICE_STATE_IDENTIFIER)















    public int getIdentifier() {















        return mIdentifier;















    }









@@ -130,6 +332,12 @@ public final class DeviceState {













        return mName;















    }





























    /**













     * @hide













     * @deprecated in favor of {@link #hasProperty(int)} method













     */













    // TODO(b/325124054): Make non-default and remove deprecated callback methods.













    @Deprecated















    @DeviceStateFlags















    public int getFlags() {















        return mFlags;









@@ -138,9 +346,9 @@ public final class DeviceState {













    @Override















    public String toString() {















        return "DeviceState{" + "identifier=" + mIdentifier + ", name='" + mName + '\''













                + ", app_accessible=" + !hasFlag(FLAG_APP_INACCESSIBLE)













                + ", app_accessible=" + !hasProperty(PROPERTY_APP_INACCESSIBLE)















                + ", cancel_when_requester_not_on_top="













                + hasFlag(FLAG_CANCEL_WHEN_REQUESTER_NOT_ON_TOP)













                + hasProperty(PROPERTY_POLICY_CANCEL_WHEN_REQUESTER_NOT_ON_TOP)















                + "}";















    }

























@@ -151,17 +359,40 @@ public final class DeviceState {













        DeviceState that = (DeviceState) o;















        return mIdentifier == that.mIdentifier















                && Objects.equals(mName, that.mName)













                && mFlags == that.mFlags;













                && Objects.equals(mProperties, that.mProperties);















    }































    @Override















    public int hashCode() {













        return Objects.hash(mIdentifier, mName, mFlags);













        return Objects.hash(mIdentifier, mName, mProperties);















    }































    /** Checks if a specific flag is set













     * @hide













     * @deprecated in favor of {@link #hasProperty(int)}















     */













    // TODO(b/325124054): Make non-default and remove deprecated callback methods.













    @Deprecated















    public boolean hasFlag(int flagToCheckFor) {















        return (mFlags & flagToCheckFor) == flagToCheckFor;















    }



























    /**













     * Checks if a specific property is set on this state













     */













    public boolean hasProperty(@DeviceStateProperties int propertyToCheckFor) {













        return mProperties.contains(propertyToCheckFor);













    }



























    /**













     * Checks if a list of properties are all set on this state













     */













    public boolean hasProperties(@NonNull @DeviceStateProperties int... properties) {













        for (int i = 0; i < properties.length; i++) {













            if (mProperties.contains(properties[i])) {













                return false;













            }













        }













        return true;













    }















}
























core/java/android/hardware/devicestate/DeviceStateManager.java



+85
−9


























File changed.
Preview size limit exceeded, changes collapsed.