1 /*
2  * Copyright (C) 2019 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.service.attention;
18 
19 import android.annotation.IntDef;
20 import android.annotation.NonNull;
21 import android.annotation.Nullable;
22 import android.annotation.SystemApi;
23 import android.app.Service;
24 import android.content.Intent;
25 import android.os.IBinder;
26 import android.os.RemoteException;
27 import android.util.Slog;
28 
29 import com.android.internal.util.Preconditions;
30 
31 import java.lang.annotation.Retention;
32 import java.lang.annotation.RetentionPolicy;
33 import java.lang.ref.WeakReference;
34 import java.util.Objects;
35 
36 
37 /**
38  * Abstract base class for Attention service.
39  *
40  * <p> An attention service provides attention estimation related features to the system.
41  * The system's default AttentionService implementation is configured in
42  * {@code config_AttentionComponent}. If this config has no value, a stub is returned.
43  *
44  * See: {@link com.android.server.attention.AttentionManagerService}.
45  *
46  * <pre>
47  * {@literal
48  * <service android:name=".YourAttentionService"
49  *          android:permission="android.permission.BIND_ATTENTION_SERVICE">
50  * </service>}
51  * </pre>
52  *
53  * @hide
54  */
55 @SystemApi
56 public abstract class AttentionService extends Service {
57     private static final String LOG_TAG = "AttentionService";
58     /**
59      * The {@link Intent} that must be declared as handled by the service. To be supported, the
60      * service must also require the {@link android.Manifest.permission#BIND_ATTENTION_SERVICE}
61      * permission so that other applications can not abuse it.
62      */
63     public static final String SERVICE_INTERFACE =
64             "android.service.attention.AttentionService";
65 
66     /** Attention is absent. */
67     public static final int ATTENTION_SUCCESS_ABSENT = 0;
68 
69     /** Attention is present. */
70     public static final int ATTENTION_SUCCESS_PRESENT = 1;
71 
72     /** Unknown reasons for failing to determine the attention. */
73     public static final int ATTENTION_FAILURE_UNKNOWN = 2;
74 
75     /** Request has been cancelled. */
76     public static final int ATTENTION_FAILURE_CANCELLED = 3;
77 
78     /** Preempted by other client. */
79     public static final int ATTENTION_FAILURE_PREEMPTED = 4;
80 
81     /** Request timed out. */
82     public static final int ATTENTION_FAILURE_TIMED_OUT = 5;
83 
84     /** Camera permission is not granted. */
85     public static final int ATTENTION_FAILURE_CAMERA_PERMISSION_ABSENT = 6;
86 
87     /** Users’ proximity is unknown (proximity sensing was inconclusive and is unsupported). */
88     public static final double PROXIMITY_UNKNOWN = -1;
89 
90     /**
91      * Result codes for when attention check was successful.
92      *
93      * @hide
94      */
95     @IntDef(prefix = {"ATTENTION_SUCCESS_"}, value = {ATTENTION_SUCCESS_ABSENT,
96             ATTENTION_SUCCESS_PRESENT})
97     @Retention(RetentionPolicy.SOURCE)
98     public @interface AttentionSuccessCodes {
99     }
100 
101     /**
102      * Result codes explaining why attention check was not successful.
103      *
104      * @hide
105      */
106     @IntDef(prefix = {"ATTENTION_FAILURE_"}, value = {ATTENTION_FAILURE_UNKNOWN,
107             ATTENTION_FAILURE_CANCELLED, ATTENTION_FAILURE_PREEMPTED, ATTENTION_FAILURE_TIMED_OUT,
108             ATTENTION_FAILURE_CAMERA_PERMISSION_ABSENT})
109     @Retention(RetentionPolicy.SOURCE)
110     public @interface AttentionFailureCodes {
111     }
112 
113     private final IAttentionService.Stub mBinder = new IAttentionService.Stub() {
114 
115         /** {@inheritDoc} */
116         @Override
117         public void checkAttention(IAttentionCallback callback) {
118             Preconditions.checkNotNull(callback);
119             AttentionService.this.onCheckAttention(new AttentionCallback(callback));
120         }
121 
122         /** {@inheritDoc} */
123         @Override
124         public void cancelAttentionCheck(IAttentionCallback callback) {
125             Preconditions.checkNotNull(callback);
126             AttentionService.this.onCancelAttentionCheck(new AttentionCallback(callback));
127         }
128 
129         /** {@inheritDoc} */
130         @Override
131         public void onStartProximityUpdates(IProximityUpdateCallback callback) {
132             Objects.requireNonNull(callback);
133             AttentionService.this.onStartProximityUpdates(new ProximityUpdateCallback(callback));
134 
135         }
136 
137         /** {@inheritDoc} */
138         @Override
139         public void onStopProximityUpdates() {
140             AttentionService.this.onStopProximityUpdates();
141         }
142     };
143 
144     @Nullable
145     @Override
onBind(@onNull Intent intent)146     public final IBinder onBind(@NonNull Intent intent) {
147         if (SERVICE_INTERFACE.equals(intent.getAction())) {
148             return mBinder;
149         }
150         return null;
151     }
152 
153     /**
154      * Checks the user attention and calls into the provided callback.
155      *
156      * @param callback the callback to return the result to
157      */
onCheckAttention(@onNull AttentionCallback callback)158     public abstract void onCheckAttention(@NonNull AttentionCallback callback);
159 
160     /**
161      * Cancels pending work for a given callback.
162      *
163      * Implementation must call back with a failure code of {@link #ATTENTION_FAILURE_CANCELLED}.
164      */
onCancelAttentionCheck(@onNull AttentionCallback callback)165     public abstract void onCancelAttentionCheck(@NonNull AttentionCallback callback);
166 
167     /**
168      * Requests the continuous updates of proximity signal via the provided callback,
169      * until {@link #onStopProximityUpdates} is called.
170      *
171      * @param callback the callback to return the result to
172      */
onStartProximityUpdates(@onNull ProximityUpdateCallback callback)173     public void onStartProximityUpdates(@NonNull ProximityUpdateCallback callback) {
174         Slog.w(LOG_TAG, "Override this method.");
175     }
176 
177     /**
178      * Requests to stop providing continuous updates until the callback is registered.
179      */
onStopProximityUpdates()180     public void onStopProximityUpdates() {
181         Slog.w(LOG_TAG, "Override this method.");
182     }
183 
184     /** Callbacks for AttentionService results. */
185     public static final class AttentionCallback {
186         @NonNull private final IAttentionCallback mCallback;
187 
AttentionCallback(@onNull IAttentionCallback callback)188         private AttentionCallback(@NonNull IAttentionCallback callback) {
189             mCallback = callback;
190         }
191 
192         /**
193          * Signals a success and provides the result code.
194          *
195          * @param timestamp of when the attention signal was computed; system throttles the requests
196          *                  so this is useful to know how fresh the result is.
197          */
onSuccess(@ttentionSuccessCodes int result, long timestamp)198         public void onSuccess(@AttentionSuccessCodes int result, long timestamp) {
199             try {
200                 mCallback.onSuccess(result, timestamp);
201             } catch (RemoteException e) {
202                 e.rethrowFromSystemServer();
203             }
204         }
205 
206         /** Signals a failure and provides the error code. */
onFailure(@ttentionFailureCodes int error)207         public void onFailure(@AttentionFailureCodes int error) {
208             try {
209                 mCallback.onFailure(error);
210             } catch (RemoteException e) {
211                 e.rethrowFromSystemServer();
212             }
213         }
214     }
215 
216     /** Callbacks for ProximityUpdateCallback results. */
217     public static final class ProximityUpdateCallback {
218         @NonNull private final WeakReference<IProximityUpdateCallback> mCallback;
219 
ProximityUpdateCallback(@onNull IProximityUpdateCallback callback)220         private ProximityUpdateCallback(@NonNull IProximityUpdateCallback callback) {
221             mCallback = new WeakReference<>(callback);
222         }
223 
224         /**
225          * @param distance the estimated distance of the user (in meter)
226          * The distance will be {@link #PROXIMITY_UNKNOWN} if the proximity sensing
227          * was inconclusive.
228          */
onProximityUpdate(double distance)229         public void onProximityUpdate(double distance) {
230             try {
231                 if (mCallback.get() != null) {
232                     mCallback.get().onProximityUpdate(distance);
233                 }
234             } catch (RemoteException e) {
235                 e.rethrowFromSystemServer();
236             }
237         }
238     }
239 }
240