• Home
  • History
  • Annotate
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1  /*
2   * Copyright (C) 2018 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.biometrics;
18  
19  import android.app.KeyguardManager;
20  import android.hardware.face.FaceManager;
21  
22  /**
23   * Interface containing all of the face-specific constants.
24   *
25   * NOTE: The error messages must be consistent between BiometricConstants, Biometric*Constants,
26   *       and the frameworks/support/biometric/.../BiometricConstants files.
27   *
28   * @hide
29   */
30  public interface BiometricFaceConstants {
31      //
32      // Accessibility constants
33      //
34      /**
35       * Require the user to look at the device during enrollment and
36       * authentication. Note this is to accommodate people who have limited
37       * vision.
38       */
39      public static final int FEATURE_REQUIRE_ATTENTION = 1;
40      /**
41       * Require a diverse set of poses during enrollment. Note this is to
42       * accommodate people with limited mobility.
43       */
44      public static final int FEATURE_REQUIRE_REQUIRE_DIVERSITY = 2;
45  
46      //
47      // Error messages from face authentication hardware during initialization, enrollment,
48      // authentication or removal. Must agree with the list in HAL h file
49      //
50      /**
51       * The hardware is unavailable. Try again later.
52       */
53      public static final int FACE_ERROR_HW_UNAVAILABLE = 1;
54  
55      /**
56       * Error state returned when the sensor was unable to process the current image.
57       */
58      public static final int FACE_ERROR_UNABLE_TO_PROCESS = 2;
59  
60      /**
61       * Error state returned when the current request has been running too long. This is intended to
62       * prevent programs from waiting for the face authentication sensor indefinitely. The timeout is
63       * platform and sensor-specific, but is generally on the order of 30 seconds.
64       */
65      public static final int FACE_ERROR_TIMEOUT = 3;
66  
67      /**
68       * Error state returned for operations like enrollment; the operation cannot be completed
69       * because there's not enough storage remaining to complete the operation.
70       */
71      public static final int FACE_ERROR_NO_SPACE = 4;
72  
73      /**
74       * The operation was canceled because the face authentication sensor is unavailable. For
75       * example, this may happen when the user is switched, the device is locked or another pending
76       * operation prevents or disables it.
77       */
78      public static final int FACE_ERROR_CANCELED = 5;
79  
80      /**
81       * The {@link FaceManager#remove} call failed. Typically this will happen when the
82       * provided face id was incorrect.
83       *
84       * @hide
85       */
86      public static final int FACE_ERROR_UNABLE_TO_REMOVE = 6;
87  
88      /**
89       * The operation was canceled because the API is locked out due to too many attempts.
90       * This occurs after 5 failed attempts, and lasts for 30 seconds.
91       */
92      public static final int FACE_ERROR_LOCKOUT = 7;
93  
94      /**
95       * Hardware vendors may extend this list if there are conditions that do not fall under one of
96       * the above categories. Vendors are responsible for providing error strings for these errors.
97       * These messages are typically reserved for internal operations such as enrollment, but may be
98       * used to express vendor errors not covered by the ones in HAL h file. Applications are
99       * expected to show the error message string if they happen, but are advised not to rely on the
100       * message id since they will be device and vendor-specific
101       */
102      public static final int FACE_ERROR_VENDOR = 8;
103  
104      /**
105       * The operation was canceled because FACE_ERROR_LOCKOUT occurred too many times.
106       * Face authentication is disabled until the user unlocks with strong authentication
107       * (PIN/Pattern/Password)
108       */
109      public static final int FACE_ERROR_LOCKOUT_PERMANENT = 9;
110  
111      /**
112       * The user canceled the operation. Upon receiving this, applications should use alternate
113       * authentication (e.g. a password). The application should also provide the means to return
114       * to face authentication, such as a "use face authentication" button.
115       */
116      public static final int FACE_ERROR_USER_CANCELED = 10;
117  
118      /**
119       * The user does not have a face enrolled.
120       */
121      public static final int FACE_ERROR_NOT_ENROLLED = 11;
122  
123      /**
124       * The device does not have a face sensor. This message will propagate if the calling app
125       * ignores the result from PackageManager.hasFeature(FEATURE_FACE) and calls
126       * this API anyway. Apps should always check for the feature before calling this API.
127       */
128      public static final int FACE_ERROR_HW_NOT_PRESENT = 12;
129  
130      /**
131       * The user pressed the negative button. This is a placeholder that is currently only used
132       * by the support library.
133       * @hide
134       */
135      public static final int FACE_ERROR_NEGATIVE_BUTTON = 13;
136  
137      /**
138       * The device does not have pin, pattern, or password set up. See
139       * {@link BiometricPrompt.Builder#setDeviceCredentialAllowed(boolean)} and
140       * {@link KeyguardManager#isDeviceSecure()}
141       */
142      public static final int BIOMETRIC_ERROR_NO_DEVICE_CREDENTIAL = 14;
143  
144      /**
145       * @hide
146       */
147      public static final int FACE_ERROR_VENDOR_BASE = 1000;
148  
149      //
150      // Image acquisition messages. These will not be sent to the user, since they conflict with
151      // existing constants. These must agree with face@1.0/types.hal.
152      //
153  
154      /**
155       * The image acquired was good.
156       */
157      public static final int FACE_ACQUIRED_GOOD = 0;
158  
159      /**
160       * The face image was not good enough to process due to a detected condition.
161       * (See {@link #FACE_ACQUIRED_TOO_BRIGHT or @link #FACE_ACQUIRED_TOO_DARK}).
162       */
163      public static final int FACE_ACQUIRED_INSUFFICIENT = 1;
164  
165      /**
166       * The face image was too bright due to too much ambient light.
167       * For example, it's reasonable to return this after multiple
168       * {@link #FACE_ACQUIRED_INSUFFICIENT}
169       * The user is expected to take action to retry in better lighting conditions
170       * when this is returned.
171       */
172      public static final int FACE_ACQUIRED_TOO_BRIGHT = 2;
173  
174      /**
175       * The face image was too dark due to illumination light obscured.
176       * For example, it's reasonable to return this after multiple
177       * {@link #FACE_ACQUIRED_INSUFFICIENT}
178       * The user is expected to take action to retry in better lighting conditions
179       * when this is returned.
180       */
181      public static final int FACE_ACQUIRED_TOO_DARK = 3;
182  
183      /**
184       * The detected face is too close to the sensor, and the image can't be processed.
185       * The user should be informed to move farther from the sensor when this is returned.
186       */
187      public static final int FACE_ACQUIRED_TOO_CLOSE = 4;
188  
189      /**
190       * The detected face is too small, as the user might be too far from the sensor.
191       * The user should be informed to move closer to the sensor when this is returned.
192       */
193      public static final int FACE_ACQUIRED_TOO_FAR = 5;
194  
195      /**
196       * Only the upper part of the face was detected. The sensor field of view is too high.
197       * The user should be informed to move up with respect to the sensor when this is returned.
198       */
199      public static final int FACE_ACQUIRED_TOO_HIGH = 6;
200  
201      /**
202       * Only the lower part of the face was detected. The sensor field of view is too low.
203       * The user should be informed to move down with respect to the sensor when this is returned.
204       */
205      public static final int FACE_ACQUIRED_TOO_LOW = 7;
206  
207      /**
208       * Only the right part of the face was detected. The sensor field of view is too far right.
209       * The user should be informed to move to the right with respect to the sensor
210       * when this is returned.
211       */
212      public static final int FACE_ACQUIRED_TOO_RIGHT = 8;
213  
214      /**
215       * Only the left part of the face was detected. The sensor field of view is too far left.
216       * The user should be informed to move to the left with respect to the sensor
217       * when this is returned.
218       */
219      public static final int FACE_ACQUIRED_TOO_LEFT = 9;
220  
221      /**
222       * The user's eyes have strayed away from the sensor. If this message is sent, the user should
223       * be informed to look at the device. If the user can't be found in the frame, one of the other
224       * acquisition messages should be sent, e.g. FACE_ACQUIRED_NOT_DETECTED.
225       */
226      public static final int FACE_ACQUIRED_POOR_GAZE = 10;
227  
228      /**
229       * No face was detected in front of the sensor.
230       * The user should be informed to point the sensor to a face when this is returned.
231       */
232      public static final int FACE_ACQUIRED_NOT_DETECTED = 11;
233  
234      /**
235       * Too much motion was detected.
236       * The user should be informed to keep their face steady relative to the
237       * sensor.
238       */
239      public static final int FACE_ACQUIRED_TOO_MUCH_MOTION = 12;
240  
241      /**
242       * The sensor needs to be re-calibrated. This is an unexpected condition, and should only be
243       * sent if a serious, uncorrectable, and unrecoverable calibration issue is detected which
244       * requires user intervention, e.g. re-enrolling. The expected response to this message is to
245       * direct the user to re-enroll.
246       */
247      public static final int FACE_ACQUIRED_RECALIBRATE = 13;
248  
249      /**
250       * The face is too different from a previous acquisition. This condition
251       * only applies to enrollment. This can happen if the user passes the
252       * device to someone else in the middle of enrollment.
253       */
254      public static final int FACE_ACQUIRED_TOO_DIFFERENT = 14;
255  
256      /**
257       * The face is too similar to a previous acquisition. This condition only
258       * applies to enrollment. The user should change their pose.
259       */
260      public static final int FACE_ACQUIRED_TOO_SIMILAR = 15;
261  
262      /**
263       * The magnitude of the pan angle of the user’s face with respect to the sensor’s
264       * capture plane is too high.
265       *
266       * The pan angle is defined as the angle swept out by the user’s face turning
267       * their neck left and right. The pan angle would be zero if the user faced the
268       * camera directly.
269       *
270       * The user should be informed to look more directly at the camera.
271       */
272      public static final int FACE_ACQUIRED_PAN_TOO_EXTREME = 16;
273  
274      /**
275       * The magnitude of the tilt angle of the user’s face with respect to the sensor’s
276       * capture plane is too high.
277       *
278       * The tilt angle is defined as the angle swept out by the user’s face looking up
279       * and down. The tilt angle would be zero if the user faced the camera directly.
280       *
281       * The user should be informed to look more directly at the camera.
282       */
283      public static final int FACE_ACQUIRED_TILT_TOO_EXTREME = 17;
284  
285      /**
286       * The magnitude of the roll angle of the user’s face with respect to the sensor’s
287       * capture plane is too high.
288       *
289       * The roll angle is defined as the angle swept out by the user’s face tilting their head
290       * towards their shoulders to the left and right. The roll angle would be zero if the user's
291       * head is vertically aligned with the camera.
292       *
293       * The user should be informed to look more directly at the camera.
294       */
295      public static final int FACE_ACQUIRED_ROLL_TOO_EXTREME = 18;
296  
297      /**
298       * The user’s face has been obscured by some object.
299       *
300       * The user should be informed to remove any objects from the line of sight from
301       * the sensor to the user’s face.
302       */
303      public static final int FACE_ACQUIRED_FACE_OBSCURED = 19;
304  
305      /**
306       * This message represents the earliest message sent at the beginning of the authentication
307       * pipeline. It is expected to be used to measure latency. For example, in a camera-based
308       * authentication system it's expected to be sent prior to camera initialization. Note this
309       * should be sent whenever authentication is restarted (see IBiometricsFace#userActivity).
310       * The framework will measure latency based on the time between the last START message and the
311       * onAuthenticated callback.
312       */
313      public static final int FACE_ACQUIRED_START = 20;
314  
315      /**
316       * The sensor is dirty. The user should be informed to clean the sensor.
317       */
318      public static final int FACE_ACQUIRED_SENSOR_DIRTY = 21;
319  
320      /**
321       * Hardware vendors may extend this list if there are conditions that do not fall under one of
322       * the above categories. Vendors are responsible for providing error strings for these errors.
323       *
324       * @hide
325       */
326      public static final int FACE_ACQUIRED_VENDOR = 22;
327  
328      /**
329       * @hide
330       */
331      public static final int FACE_ACQUIRED_VENDOR_BASE = 1000;
332  }
333