1 /* 2 * Copyright (C) 2021 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 android.hardware.devicestate; 18 19 import android.annotation.IntDef; 20 import android.annotation.NonNull; 21 import android.annotation.TestApi; 22 23 import java.lang.annotation.Retention; 24 import java.lang.annotation.RetentionPolicy; 25 import java.util.concurrent.Executor; 26 27 /** 28 * A request to alter the state of the device managed by {@link DeviceStateManager}. 29 * <p> 30 * Once constructed, a {@link DeviceStateRequest request} can be submitted with a call to 31 * {@link DeviceStateManager#requestState(DeviceStateRequest, Executor, 32 * DeviceStateRequest.Callback)}. 33 * <p> 34 * By default, the request is kept active until a call to 35 * {@link DeviceStateManager#cancelRequest(DeviceStateRequest)} or until one of the following 36 * occurs: 37 * <ul> 38 * <li>Another processes submits a request succeeding this request in which case the request 39 * will be suspended until the interrupting request is canceled. 40 * <li>The requested state has become unsupported. 41 * <li>The process submitting the request dies. 42 * </ul> 43 * However, this behavior can be changed by setting flags on the request. For example, the 44 * {@link #FLAG_CANCEL_WHEN_BASE_CHANGES} flag will extend this behavior to also cancel the 45 * request whenever the base (non-override) device state changes. 46 * 47 * @see DeviceStateManager 48 * 49 * @hide 50 */ 51 @TestApi 52 public final class DeviceStateRequest { 53 /** 54 * Flag that indicates the request should be canceled automatically when the base 55 * (non-override) device state changes. Useful when the requestor only wants the request to 56 * remain active while the base state remains constant and automatically cancel when the user 57 * manipulates the device into a different state. 58 */ 59 public static final int FLAG_CANCEL_WHEN_BASE_CHANGES = 1 << 0; 60 61 /** @hide */ 62 @IntDef(prefix = {"FLAG_"}, flag = true, value = { 63 FLAG_CANCEL_WHEN_BASE_CHANGES, 64 }) 65 @Retention(RetentionPolicy.SOURCE) 66 public @interface RequestFlags {} 67 68 /** 69 * Creates a new {@link Builder} for a {@link DeviceStateRequest}. Must be one of the supported 70 * states for the device which can be queried with a call to 71 * {@link DeviceStateManager#getSupportedStates()}. 72 * 73 * @param requestedState the device state being requested. 74 */ 75 @NonNull newBuilder(int requestedState)76 public static Builder newBuilder(int requestedState) { 77 return new Builder(requestedState); 78 } 79 80 /** 81 * Builder for {@link DeviceStateRequest}. An instance can be obtained through 82 * {@link #newBuilder(int)}. 83 */ 84 public static final class Builder { 85 private final int mRequestedState; 86 private int mFlags; 87 Builder(int requestedState)88 private Builder(int requestedState) { 89 mRequestedState = requestedState; 90 } 91 92 /** 93 * Sets the flag bits provided within {@code flags} with all other bits remaining 94 * unchanged. 95 */ 96 @NonNull setFlags(@equestFlags int flags)97 public Builder setFlags(@RequestFlags int flags) { 98 mFlags |= flags; 99 return this; 100 } 101 102 /** 103 * Returns a new {@link DeviceStateRequest} object whose state matches the state set on the 104 * builder. 105 */ 106 @NonNull build()107 public DeviceStateRequest build() { 108 return new DeviceStateRequest(mRequestedState, mFlags); 109 } 110 } 111 112 /** Callback to track the status of a request. */ 113 public interface Callback { 114 /** 115 * Called to indicate the request has become active and the device state will match the 116 * requested state. 117 * <p> 118 * Guaranteed to be called after a call to 119 * {@link DeviceStateManager.DeviceStateCallback#onStateChanged(int)} with a state 120 * matching the requested state. 121 */ onRequestActivated(@onNull DeviceStateRequest request)122 default void onRequestActivated(@NonNull DeviceStateRequest request) {} 123 124 /** 125 * Called to indicate the request has been temporarily suspended. 126 * <p> 127 * Guaranteed to be called before a call to 128 * {@link DeviceStateManager.DeviceStateCallback#onStateChanged(int)}. 129 */ onRequestSuspended(@onNull DeviceStateRequest request)130 default void onRequestSuspended(@NonNull DeviceStateRequest request) {} 131 132 /** 133 * Called to indicate the request has been canceled. The request can be resubmitted with 134 * another call to {@link DeviceStateManager#requestState(DeviceStateRequest, Executor, 135 * DeviceStateRequest.Callback)}. 136 * <p> 137 * Guaranteed to be called before a call to 138 * {@link DeviceStateManager.DeviceStateCallback#onStateChanged(int)}. 139 * <p> 140 * Note: A call to {@link #onRequestSuspended(DeviceStateRequest)} is not guaranteed to 141 * occur before this method. 142 */ onRequestCanceled(@onNull DeviceStateRequest request)143 default void onRequestCanceled(@NonNull DeviceStateRequest request) {} 144 } 145 146 private final int mRequestedState; 147 @RequestFlags 148 private final int mFlags; 149 DeviceStateRequest(int requestedState, @RequestFlags int flags)150 private DeviceStateRequest(int requestedState, @RequestFlags int flags) { 151 mRequestedState = requestedState; 152 mFlags = flags; 153 } 154 getState()155 public int getState() { 156 return mRequestedState; 157 } 158 159 @RequestFlags getFlags()160 public int getFlags() { 161 return mFlags; 162 } 163 } 164