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