1 /* 2 * Copyright (C) 2020 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.server.devicestate; 18 19 import static android.hardware.devicestate.DeviceStateManager.MAXIMUM_DEVICE_STATE_IDENTIFIER; 20 import static android.hardware.devicestate.DeviceStateManager.MINIMUM_DEVICE_STATE_IDENTIFIER; 21 22 import android.annotation.IntDef; 23 import android.annotation.IntRange; 24 import android.hardware.devicestate.DeviceState; 25 import android.util.Dumpable; 26 27 import java.lang.annotation.Retention; 28 import java.lang.annotation.RetentionPolicy; 29 30 /** 31 * Responsible for providing the set of supported {@link DeviceState.Configuration device states} as 32 * well as the current device state. 33 * 34 * @see DeviceStatePolicy 35 */ 36 public interface DeviceStateProvider extends Dumpable { 37 int SUPPORTED_DEVICE_STATES_CHANGED_DEFAULT = 0; 38 39 /** 40 * Indicating that the supported device states changed callback is trigger for initial listener 41 * registration. 42 */ 43 int SUPPORTED_DEVICE_STATES_CHANGED_INITIALIZED = 1; 44 45 /** 46 * Indicating that the supported device states have changed because the thermal condition 47 * returned to normal status from critical status. 48 */ 49 int SUPPORTED_DEVICE_STATES_CHANGED_THERMAL_NORMAL = 2; 50 51 /** 52 * Indicating that the supported device states have changed because of thermal critical 53 * condition. 54 */ 55 int SUPPORTED_DEVICE_STATES_CHANGED_THERMAL_CRITICAL = 3; 56 57 /** 58 * Indicating that the supported device states have changed because power save mode was enabled. 59 */ 60 int SUPPORTED_DEVICE_STATES_CHANGED_POWER_SAVE_ENABLED = 4; 61 62 /** 63 * Indicating that the supported device states have changed because power save mode was 64 * disabled. 65 */ 66 int SUPPORTED_DEVICE_STATES_CHANGED_POWER_SAVE_DISABLED = 5; 67 68 /** 69 * Indicating that the supported device states have changed because an external display was 70 * added. 71 */ 72 int SUPPORTED_DEVICE_STATES_CHANGED_EXTERNAL_DISPLAY_ADDED = 6; 73 74 /** 75 * Indicating that the supported device states have changed because an external display was 76 * removed. 77 */ 78 int SUPPORTED_DEVICE_STATES_CHANGED_EXTERNAL_DISPLAY_REMOVED = 7; 79 80 @IntDef(prefix = { "SUPPORTED_DEVICE_STATES_CHANGED_" }, value = { 81 SUPPORTED_DEVICE_STATES_CHANGED_DEFAULT, 82 SUPPORTED_DEVICE_STATES_CHANGED_INITIALIZED, 83 SUPPORTED_DEVICE_STATES_CHANGED_THERMAL_NORMAL, 84 SUPPORTED_DEVICE_STATES_CHANGED_THERMAL_CRITICAL, 85 SUPPORTED_DEVICE_STATES_CHANGED_POWER_SAVE_ENABLED, 86 SUPPORTED_DEVICE_STATES_CHANGED_POWER_SAVE_DISABLED, 87 SUPPORTED_DEVICE_STATES_CHANGED_EXTERNAL_DISPLAY_ADDED, 88 SUPPORTED_DEVICE_STATES_CHANGED_EXTERNAL_DISPLAY_REMOVED 89 }) 90 @Retention(RetentionPolicy.SOURCE) 91 @interface SupportedStatesUpdatedReason {} 92 93 /** 94 * Registers a listener for changes in provider state. 95 * <p> 96 * It is <b>required</b> that 97 * {@link Listener#onSupportedDeviceStatesChanged(DeviceState[], int)} be called followed by 98 * {@link Listener#onStateChanged(int)} with the initial values on successful registration of 99 * the listener. 100 */ setListener(Listener listener)101 void setListener(Listener listener); 102 103 /** Callback for changes in {@link DeviceStateProvider} state. */ 104 interface Listener { 105 /** 106 * Called to notify the listener of a change in supported {@link DeviceState device states}. 107 * Required to be called once on successful registration of the listener and then once on 108 * every subsequent change in supported device states. 109 * <p> 110 * The set of device states can change based on the current hardware state of the device. 111 * For example, if a device state depends on a particular peripheral device (display, etc) 112 * it would only be reported as supported when the device is plugged. Otherwise, it should 113 * not be included in the set of supported states. 114 * <p> 115 * The identifier for every provided device state must be unique and greater than or equal 116 * to zero and there must always be at least one supported device state. 117 * 118 * @param newDeviceStates array of supported device states. 119 * @param reason the reason for the supported device states change. 120 * 121 * @throws IllegalArgumentException if the list of device states is empty or if one of the 122 * provided states contains an invalid identifier. 123 */ onSupportedDeviceStatesChanged(DeviceState[] newDeviceStates, @SupportedStatesUpdatedReason int reason)124 void onSupportedDeviceStatesChanged(DeviceState[] newDeviceStates, 125 @SupportedStatesUpdatedReason int reason); 126 127 /** 128 * Called to notify the listener of a change in current device state. Required to be called 129 * once on successful registration of the listener and then once on every subsequent change 130 * in device state. Value must have been included in the set of supported device states 131 * provided in the most recent call to 132 * {@link #onSupportedDeviceStatesChanged(DeviceState[], int)}. 133 * 134 * @param identifier the identifier of the new device state. 135 * 136 * @throws IllegalArgumentException if the state is less than 137 * {@link MINIMUM_DEVICE_STATE_IDENTIFIER} or greater than 138 * {@link MAXIMUM_DEVICE_STATE_IDENTIFIER}. 139 */ onStateChanged( @ntRangefrom = MINIMUM_DEVICE_STATE_IDENTIFIER, to = MAXIMUM_DEVICE_STATE_IDENTIFIER) int identifier)140 void onStateChanged( 141 @IntRange(from = MINIMUM_DEVICE_STATE_IDENTIFIER, to = 142 MAXIMUM_DEVICE_STATE_IDENTIFIER) int identifier); 143 } 144 } 145