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
17package android.hardware.biometrics.face@1.0;
18
19/**
20 * This callback interface is used by clients to recieve updates from the face
21 * HAL.
22 */
23interface IBiometricsFaceClientCallback {
24
25    /**
26     * A callback invoked when one enrollment step has been completed.
27     *
28     * @param deviceId A unique id associated with the HAL implementation
29     *     service that processed this enrollment step.
30     * @param faceId The id of the face template being enrolled.
31     * @param userId The active user id for the template being enrolled.
32     * @param remaining The number of remaining steps before enrolllment is
33     *     complete or 0 if enrollment has completed successfully.
34     */
35    oneway onEnrollResult(uint64_t deviceId, uint32_t faceId, int32_t userId,
36        uint32_t remaining);
37
38    /**
39     * A callback invoked when a face has been successfully authenticated.
40     *
41     * @param deviceId A unique id associated with the HAL implementation
42     *     service that processed this authentication attempt.
43     * @param faceId The id of the face template that passed the authentication
44     *     challenge.
45     * @param userId The active user id for the authenticated face.
46     * @param token The hardware authentication token associated with this
47     *     authenticate operation.
48     */
49    oneway onAuthenticated(uint64_t deviceId, uint32_t faceId, int32_t userId,
50        vec<uint8_t> token);
51
52    /**
53     * A callback invoked when a face is acquired.
54     *
55     * If a non-critical, recoverable error occurs during an enrollment or
56     * authentication attempt, the HAL implementation must invoke this callback
57     * to allow clients to inform the user that some actionable change must be
58     * made.
59     *
60     * @param deviceId A unique id associated with the HAL implementation
61     *     service that acquired a face.
62     * @param userId The id of the active user associated with the attempted
63     *     face acquisition.
64     * @param acquiredInfo A message about the quality of the acquired image.
65     * @param vendorCode An optional vendor-specific message. This is only valid
66     *     when acquiredInfo == FaceAcquiredInfo.VENDOR. This message is opaque
67     *     to the framework, and vendors must provide code to handle it. For
68     *     example this can be used to guide enrollment in Settings or provide
69     *     a message during authentication that is vendor-specific. The vendor
70     *     is expected to provide help strings to cover all known values.
71     */
72     oneway onAcquired(uint64_t deviceId, int32_t userId,
73         FaceAcquiredInfo acquiredInfo, int32_t vendorCode);
74
75    /**
76     * A callback invoked when an error has occured.
77     *
78     * @param deviceId A unique id associated with the HAL implementation
79     *     service where this error occured.
80     * @param userId The id of the active user when the error occured, or
81     *     UserHandle::NONE if an active user had not been set yet.
82     * @param error A message about the error that occurred.
83     * @param vendorCode An optional, vendor-speicifc error message. Only valid
84     *     when error == FaceError.VENDOR. This message is opaque to the
85     *     framework, and vendors must provide code to handle it. For example,
86     *     this scan be used to show the user an error message specific to the
87     *     device. The vendor is expected to provide error strings to cover
88     *     all known values.
89     */
90    oneway onError(uint64_t deviceId, int32_t userId, FaceError error,
91        int32_t vendorCode);
92
93    /**
94     * A callback invoked when a face template has been removed.
95     *
96     * @param deviceId A unique id associated with the HAL implementation
97     *     service that processed this removal.
98     * @param removed A list of ids that were removed.
99     * @param userId The active user id for the removed face template.
100     */
101    oneway onRemoved(uint64_t deviceId, vec<uint32_t> removed, int32_t userId);
102
103    /**
104     * A callback invoked to enumerate all current face templates.
105     *
106     * @param deviceId A unique id associated with the HAL implementation
107     *     service that processed this enumeration.
108     * @param faceIds A list of ids of all currently enrolled face templates.
109     * @param userId The active user id for the enumerated face template.
110     */
111    oneway onEnumerate(uint64_t deviceId, vec<uint32_t> faceIds,
112        int32_t userId);
113
114    /**
115     * A callback invoked when the lockout state changes.
116     *
117     * This method must only be invoked when setActiveUser() is called,
118     * when lockout starts, and when lockout ends. When lockout starts,
119     * duration must be greater than 0, and when lockout ends, duration must
120     * be 0. This must be called before calling onError() with parameters
121     * LOCKOUT or LOCKOUT_PERMANENT. If the user is permanently locked out,
122     * the duration must be MAX_UINT64.
123     *
124     * @param duration the remaining lockout duration in milliseconds, or 0
125     *     if the user is not locked out.
126     */
127    oneway onLockoutChanged(uint64_t duration);
128};
129