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 android.hardware.lights;
18 
19 import android.annotation.IntDef;
20 import android.annotation.NonNull;
21 import android.annotation.SystemApi;
22 import android.annotation.SystemService;
23 import android.annotation.TestApi;
24 import android.content.Context;
25 import android.os.Binder;
26 import android.os.IBinder;
27 
28 import com.android.internal.util.Preconditions;
29 
30 import java.lang.annotation.Retention;
31 import java.lang.annotation.RetentionPolicy;
32 import java.util.List;
33 
34 /**
35  * The LightsManager class allows control over device lights.
36  *
37  */
38 @SystemService(Context.LIGHTS_SERVICE)
39 public abstract class LightsManager {
40     private static final String TAG = "LightsManager";
41 
42     @NonNull private final Context mContext;
43     // These enum values copy the values from {@link com.android.server.lights.LightsManager}
44     // and the light HAL. Since 0-7 are lights reserved for system use, only the microphone light
45     // and following types are available through this API.
46     /** Type for lights that indicate microphone usage
47      * @deprecated this has been moved to {@link android.hardware.lights.Light }
48      * @hide
49      */
50     @Deprecated
51     @SystemApi
52     public static final int LIGHT_TYPE_MICROPHONE = 8;
53 
54     /** @hide */
55     @Retention(RetentionPolicy.SOURCE)
56     @IntDef(prefix = {"LIGHT_TYPE_"},
57         value = {
58             LIGHT_TYPE_MICROPHONE,
59         })
60     public @interface LightType {}
61 
62     /**
63      * @hide to prevent subclassing from outside of the framework
64      */
LightsManager(Context context)65     public LightsManager(Context context) {
66         mContext = Preconditions.checkNotNull(context);
67     }
68 
69     /**
70      * Returns the lights available on the device.
71      *
72      * @return A list of available lights
73      */
getLights()74     public @NonNull abstract List<Light> getLights();
75 
76     /**
77      * Returns the state of a specified light.
78      *
79      */
getLightState(@onNull Light light)80     public abstract @NonNull LightState getLightState(@NonNull Light light);
81 
82     /**
83      * Creates a new LightsSession that can be used to control the device lights.
84      */
openSession()85     public abstract @NonNull LightsSession openSession();
86 
87     /**
88      *
89      * Creates a new {@link LightsSession}
90      *
91      * @param priority the larger this number, the higher the priority of this session when multiple
92      *                 light state requests arrive simultaneously.
93      *
94      * @hide
95      */
96     @TestApi
openSession(int priority)97     public abstract @NonNull LightsSession openSession(int priority);
98 
99     /**
100      * Encapsulates a session that can be used to control device lights and represents the lifetime
101      * of the requests.
102      *
103      * <p>Any lights requests always live in a lights session which defines the lifecycle of the
104      * lights requests. A lights session is AutoCloseable that will get closed when leaving the
105      * session context.
106      *
107      * <p>Multiple sessions can make lights requests which contains same light. In the case the
108      * LightsManager implementation will arbitrate and honor one of the session's request. When
109      * the session hold the current light request closed, LightsManager implementation will choose
110      * another live session to honor its lights requests.
111      */
112     public abstract static class LightsSession implements AutoCloseable {
113         private final IBinder mToken = new Binder();
114 
115         /**
116          * @hide to prevent subclassing from outside of the framework
117          */
LightsSession()118         public LightsSession() {
119         }
120 
121         /**
122          * Sends a request to modify the states of multiple lights.
123          *
124          * @param request the settings for lights that should change
125          */
requestLights(@onNull LightsRequest request)126         public abstract void requestLights(@NonNull LightsRequest request);
127 
128         @Override
close()129         public abstract void close();
130 
131         /**
132          * Get the token of a light session.
133          *
134          * @return Binder token of the light session.
135          * @hide
136          */
getToken()137         public @NonNull IBinder getToken() {
138             return mToken;
139         }
140     }
141 
142 }
143