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;
20 import static android.hardware.devicestate.DeviceStateManager.MINIMUM_DEVICE_STATE;
21 
22 import android.annotation.IntDef;
23 import android.annotation.IntRange;
24 
25 import java.lang.annotation.Retention;
26 import java.lang.annotation.RetentionPolicy;
27 
28 /**
29  * Responsible for providing the set of supported {@link DeviceState device states} as well as the
30  * current device state.
31  *
32  * @see DeviceStatePolicy
33  */
34 public interface DeviceStateProvider {
35     int SUPPORTED_DEVICE_STATES_CHANGED_DEFAULT = 0;
36 
37     /**
38      * Indicating that the supported device states changed callback is trigger for initial listener
39      * registration.
40      */
41     int SUPPORTED_DEVICE_STATES_CHANGED_INITIALIZED = 1;
42 
43     /**
44      * Indicating that the supported device states have changed because the thermal condition
45      * returned to normal status from critical status.
46      */
47     int SUPPORTED_DEVICE_STATES_CHANGED_THERMAL_NORMAL = 2;
48 
49     /**
50      * Indicating that the supported device states have changed because of thermal critical
51      * condition.
52      */
53     int SUPPORTED_DEVICE_STATES_CHANGED_THERMAL_CRITICAL = 3;
54 
55     /**
56      * Indicating that the supported device states have changed because power save mode was enabled.
57      */
58     int SUPPORTED_DEVICE_STATES_CHANGED_POWER_SAVE_ENABLED = 4;
59 
60     /**
61      * Indicating that the supported device states have changed because power save mode was
62      * disabled.
63      */
64     int SUPPORTED_DEVICE_STATES_CHANGED_POWER_SAVE_DISABLED = 5;
65 
66     @IntDef(prefix = { "SUPPORTED_DEVICE_STATES_CHANGED_" }, value = {
67             SUPPORTED_DEVICE_STATES_CHANGED_DEFAULT,
68             SUPPORTED_DEVICE_STATES_CHANGED_INITIALIZED,
69             SUPPORTED_DEVICE_STATES_CHANGED_THERMAL_NORMAL,
70             SUPPORTED_DEVICE_STATES_CHANGED_THERMAL_CRITICAL,
71             SUPPORTED_DEVICE_STATES_CHANGED_POWER_SAVE_ENABLED,
72             SUPPORTED_DEVICE_STATES_CHANGED_POWER_SAVE_DISABLED
73     })
74     @Retention(RetentionPolicy.SOURCE)
75     @interface SupportedStatesUpdatedReason {}
76 
77     /**
78      * Registers a listener for changes in provider state.
79      * <p>
80      * It is <b>required</b> that
81      * {@link Listener#onSupportedDeviceStatesChanged(DeviceState[], int)} be called followed by
82      * {@link Listener#onStateChanged(int)} with the initial values on successful registration of
83      * the listener.
84      */
setListener(Listener listener)85     void setListener(Listener listener);
86 
87     /** Callback for changes in {@link DeviceStateProvider} state. */
88     interface Listener {
89         /**
90          * Called to notify the listener of a change in supported {@link DeviceState device states}.
91          * Required to be called once on successful registration of the listener and then once on
92          * every subsequent change in supported device states.
93          * <p>
94          * The set of device states can change based on the current hardware state of the device.
95          * For example, if a device state depends on a particular peripheral device (display, etc)
96          * it would only be reported as supported when the device is plugged. Otherwise, it should
97          * not be included in the set of supported states.
98          * <p>
99          * The identifier for every provided device state must be unique and greater than or equal
100          * to zero and there must always be at least one supported device state.
101          *
102          * @param newDeviceStates array of supported device states.
103          * @param reason the reason for the supported device states change.
104          *
105          * @throws IllegalArgumentException if the list of device states is empty or if one of the
106          * provided states contains an invalid identifier.
107          */
onSupportedDeviceStatesChanged(DeviceState[] newDeviceStates, @SupportedStatesUpdatedReason int reason)108         void onSupportedDeviceStatesChanged(DeviceState[] newDeviceStates,
109                 @SupportedStatesUpdatedReason int reason);
110 
111         /**
112          * Called to notify the listener of a change in current device state. Required to be called
113          * once on successful registration of the listener and then once on every subsequent change
114          * in device state. Value must have been included in the set of supported device states
115          * provided in the most recent call to
116          * {@link #onSupportedDeviceStatesChanged(DeviceState[], int)}.
117          *
118          * @param identifier the identifier of the new device state.
119          *
120          * @throws IllegalArgumentException if the state is less than {@link MINIMUM_DEVICE_STATE}
121          * or greater than {@link MAXIMUM_DEVICE_STATE}.
122          */
onStateChanged( @ntRangefrom = MINIMUM_DEVICE_STATE, to = MAXIMUM_DEVICE_STATE) int identifier)123         void onStateChanged(
124                 @IntRange(from = MINIMUM_DEVICE_STATE, to = MAXIMUM_DEVICE_STATE) int identifier);
125     }
126 }
127