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.IntRange; 23 24 /** 25 * Responsible for providing the set of supported {@link DeviceState device states} as well as the 26 * current device state. 27 * 28 * @see DeviceStatePolicy 29 */ 30 public interface DeviceStateProvider { 31 /** 32 * Registers a listener for changes in provider state. 33 * <p> 34 * It is <b>required</b> that {@link Listener#onSupportedDeviceStatesChanged(DeviceState[])} be 35 * called followed by {@link Listener#onStateChanged(int)} with the initial values on successful 36 * registration of the listener. 37 */ setListener(Listener listener)38 void setListener(Listener listener); 39 40 /** Callback for changes in {@link DeviceStateProvider} state. */ 41 interface Listener { 42 /** 43 * Called to notify the listener of a change in supported {@link DeviceState device states}. 44 * Required to be called once on successful registration of the listener and then once on 45 * every subsequent change in supported device states. 46 * <p> 47 * The set of device states can change based on the current hardware state of the device. 48 * For example, if a device state depends on a particular peripheral device (display, etc) 49 * it would only be reported as supported when the device is plugged. Otherwise, it should 50 * not be included in the set of supported states. 51 * <p> 52 * The identifier for every provided device state must be unique and greater than or equal 53 * to zero and there must always be at least one supported device state. 54 * 55 * @param newDeviceStates array of supported device states. 56 * 57 * @throws IllegalArgumentException if the list of device states is empty or if one of the 58 * provided states contains an invalid identifier. 59 */ onSupportedDeviceStatesChanged(DeviceState[] newDeviceStates)60 void onSupportedDeviceStatesChanged(DeviceState[] newDeviceStates); 61 62 /** 63 * Called to notify the listener of a change in current device state. Required to be called 64 * once on successful registration of the listener and then once on every subsequent change 65 * in device state. Value must have been included in the set of supported device states 66 * provided in the most recent call to 67 * {@link #onSupportedDeviceStatesChanged(DeviceState[])}. 68 * 69 * @param identifier the identifier of the new device state. 70 * 71 * @throws IllegalArgumentException if the state is less than {@link MINIMUM_DEVICE_STATE} 72 * or greater than {@link MAXIMUM_DEVICE_STATE}. 73 */ onStateChanged( @ntRangefrom = MINIMUM_DEVICE_STATE, to = MAXIMUM_DEVICE_STATE) int identifier)74 void onStateChanged( 75 @IntRange(from = MINIMUM_DEVICE_STATE, to = MAXIMUM_DEVICE_STATE) int identifier); 76 } 77 } 78